diff options
| author | Martin Burnicki <martin.burnicki@meinberg.de> | 2019-10-25 12:00:00 +0200 |
|---|---|---|
| committer | Martin Burnicki <martin.burnicki@meinberg.de> | 2019-10-25 12:00:00 +0200 |
| commit | 0ee32041009a4e3c2f086891a924e14a104948a6 (patch) | |
| tree | 40ab5c5ab967887cb46d09cf5dcd0774955f5eed | |
| parent | c9987ad4cd9912560bb5373073dfad462dc2de9d (diff) | |
| download | mbgsdk-win-0ee32041009a4e3c2f086891a924e14a104948a6.tar.gz mbgsdk-win-0ee32041009a4e3c2f086891a924e14a104948a6.zip | |
Update mbglib files for the C demo projects
52 files changed, 33299 insertions, 11704 deletions
diff --git a/c/mbglib/common/mbgerror.c b/c/mbglib/common/mbgerror.c new file mode 100644 index 0000000..67ad2b2 --- /dev/null +++ b/c/mbglib/common/mbgerror.c @@ -0,0 +1,1203 @@ + +/************************************************************************** + * + * $Id: mbgerror.c 1.9.1.1 2019/09/23 16:08:30Z martin TRASH $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Meinberg Library to communicate with USB devices from user space + * + * ----------------------------------------------------------------------- + * $Log: mbgerror.c $ + * Revision 1.9.1.1 2019/09/23 16:08:30Z martin + * Preliminary doxygen changes. + * Revision 1.9 2019/08/26 15:15:10 martin + * Translate POSIX ENODATA to MBG_ERR_NO_DATA. + * Revision 1.8 2019/08/20 08:22:51 martin + * Translate win32 ERROR_FILE_NOT_FOUND to MBG_ERR_NO_ENTITY. + * Revision 1.7 2019/04/03 12:53:55 martin + * Use new code MBG_ERR_BAD_ADDR. + * Revision 1.6 2018/11/22 14:47:15 martin + * Support QNX target. + * New function mbg_win32_ntstatus_to_mbg(). + * Added and renamed static code conversion tables. + * Added and updated doxygen comments. + * Revision 1.5 2018/09/21 09:44:38 martin + * Renamed mbg_win32_last_err_to_mbg() to + * mbg_win32_sys_err_to_mbg(). + * Translate win32 error codes ERROR_BUFFER_OVERFLOW + * and ERROR_INSUFFICIENT_BUFFER. + * Updated some comments. + * Revision 1.4 2018/06/25 14:21:09Z martin + * Cleaned up definition and usage of control macros. + * Distinguish between kernel mode and user mode on Windows. + * Support some new error codes. + * Revision 1.3 2017/07/05 09:20:07 martin + * Fixed a bug where POSIX error ENODEV wasn't mapped at all, but + * EXDEV was instead translated erraneously to MBG_ERR_NO_DEV. + * Mapped POSIX error ENOSPC to MBG_ERR_NO_SPACE, and EFAULT + * to MBG_ERR_INV_PARM. + * Mapped Windows WSA error codes WSAEFAULT and WSAEINVAL + * to MBG_ERR_INV_PARM. + * Renamed mbg_ioctl_err() to mbg_cond_err_msg(). + * New function mbg_cond_err_msg_info() which takes an optional + * info string which is printed if the error code to be checked + * is MBG_ERR_NOT_SUPP_BY_DEV. + * Fixed build in Windows kernel mode. + * Fixed syntax error in CVI-specific code. + * Quieted some compiler warnings. + * Revision 1.2 2016/08/05 12:25:44Z martin + * Added some functions. + * Revision 1.1 2014/03/07 12:08:14 martin + * Initial revision. + * + **************************************************************************/ + +#define _MBGERROR + #include <mbgerror.h> +#undef _MBGERROR + +#include <mbg_tgt.h> + +#if defined( MBG_TGT_WIN32 ) + + #if !defined( MBG_TGT_KERNEL ) + #include <errno.h> + #include <stdio.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_HAS_WIN32_ERR_API 1 + #else + #include <mbgddmsg.h> + + #define _MBG_TGT_OMIT_LAST_ERROR 1 + #define _MBG_TGT_OMIT_ERR_MSG 1 // Not (yet) supported in Windows kernel mode + #endif + +#elif defined( MBG_TGT_CVI ) + + // Nothing to do here. + +#elif defined( MBG_TGT_LINUX ) + + #if !defined( MBG_TGT_KERNEL ) + #include <errno.h> + #include <stdio.h> + #include <string.h> + #include <netdb.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_HAS_POSIX_H_ERRNO 1 + #else + #include <asm/errno.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_OMIT_LAST_ERROR 1 + #define _MBG_TGT_OMIT_ERR_MSG 1 + #endif + +#elif defined( MBG_TGT_BSD ) + + #if !defined( MBG_TGT_KERNEL ) + #include <errno.h> + #include <stdio.h> + #include <string.h> + #include <netdb.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_HAS_POSIX_H_ERRNO 1 + #else + #include <sys/errno.h> + #if defined( MBG_TGT_FREEBSD ) + #include <sys/stddef.h> // NULL + #elif defined( MBG_TGT_NETBSD ) + #include <sys/null.h> // NULL + #endif + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_OMIT_LAST_ERROR 1 + #define _MBG_TGT_OMIT_ERR_MSG 1 + #endif + +#elif defined( MBG_TGT_QNX_NTO ) // QNX 6.x only, but not QNX 4.x + + #include <stdio.h> + #include <errno.h> + #include <string.h> + #include <netdb.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_HAS_POSIX_H_ERRNO 1 + +#elif defined( MBG_TGT_DOS ) + + #include <stdio.h> + #include <stdlib.h> + #include <stddef.h> + #include <errno.h> + + #define _MBG_TGT_HAS_POSIX_ERRNO 1 + #define _MBG_TGT_OMIT_SOCKET_ERRORS 1 // No network socket support by OS + +#endif + +#if defined( USE_MBG_ZLIB ) + #include <zlib.h> +#endif + +#if !defined( DEBUG ) + // FIXME This should be done globally across projects. + #define DEBUG 0 +#endif + + +typedef struct +{ + int srch_errno; + int mapped_errno; + +} ERRNO_CNV_ENTRY; + + + +#if defined( _MBG_TGT_HAS_POSIX_ERRNO ) + +/** + * @brief Mappings between Meinberg error codes and POSIX error codes + * + * Always refer to the symbolic names only. The numeric codes listed + * in the comments below are just for a quick reference, and may vary + * depending on the OS type and version. + * + * Linux: /usr/include/asm-generic/errno.h<br> + * FreeBSD/NetBSD: /usr/include/sys/errno.h + * + * @see ::mbg_posix_errno_to_mbg + * @see POSIX spec at http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_03 + */ +static ERRNO_CNV_ENTRY posix_errno_table[] = +{ + { EPERM, MBG_ERR_PERM }, // 1, Operation not permitted (e.g. when trying to set time without sufficient permissions). + { ENOENT, MBG_ERR_NO_ENTITY }, // 2, No such file or directory. + // { ESRCH, }, // 3, No such process. + { EINTR, MBG_ERR_INTR }, // 4, Interrupted function call. + { EIO, MBG_ERR_IO }, // 5, Input/output error (from physical device). + { ENXIO, MBG_ERR_NOT_FOUND }, // 6, No such device or address (refering to a device that doesn't exist, or request beyond its capabilities) of the device. + // { E2BIG, }, // 7, Argument list too long (or lack of space in an output buffer, or argument exceeds system-imposed maximum. + // { ENOEXEC, }, // 8, Exec format error (executable file format error). + // { EBADF, }, // 9, Bad file number/descriptor (or a read (write) tried on a file only open for writing (reading)). + // { ECHILD, }, // 10, No child processes (when waiting for child process). + { EAGAIN, MBG_ERR_AGAIN }, // 11, Try again, resource temporarily unavailable (later calls may complete normally, maybe same as EWOULDBLOCK). + { ENOMEM, MBG_ERR_NO_MEM }, // 12, Out of memory (can't allocate memory). + { EACCES, MBG_ERR_ACCESS }, // 13, Permission denied (e.g. when trying to access a device without sufficient permissions). + { EFAULT, MBG_ERR_BAD_ADDRESS }, // 14, Bad address (e.g. invalid address in a function argument). + // { ENOTBLK, }, // 15, Block device required (eventually no POSIX error, but supported in Linux and *BSD). + { EBUSY, MBG_ERR_BUSY }, // 16, Device or resource busy. + { EEXIST, MBG_ERR_EXIST }, // 17, File exists. + // { EXDEV, }, // 18, Cross-device link. + { ENODEV, MBG_ERR_NO_DEV }, // 19, ### No such device (operation not supported by device). + // { ENOTDIR, }, // 20, Not a directory (when a directory was expected for the operation). + // { EISDIR, }, // 21, Is a directory (when a directory was *not* expected for the operation). + { EINVAL, MBG_ERR_INV_PARM }, // 22, Invalid argument (was supplied to a function). + // { ENFILE, }, // 23, Too many files open in system (file table overflow). + // { EMFILE, }, // 24, Too many open files (or file descriptor value too large). + { ENOTTY, MBG_ERR_NOT_SUPP_BY_DEV }, // 25, ### Not a typewriter (actually means "inappropriate I/O control for device"). + // { ETXTBSY, }, // 26, Text file busy ("text" actually means "binary program file"). + // { EFBIG, }, // 27, File too large. + { ENOSPC, MBG_ERR_NO_SPACE }, // 28, No space left on device (when writing a file or extending directory). + { ESPIPE, MBG_ERR_PIPE }, // 29, Illegal seek (when attempting to access the file offset associated with a pipe or FIFO). + // { EROFS, }, // 30, Read-only file system. + // { EMLINK, }, // 31, Too many links (link count of a single file exceed). + // { EPIPE, }, // 32, Broken pipe (writing to a socket, pipe, or FIFO which has no process to read the data). + // { EDOM, }, // 33, Math argument out of domain of function. + { ERANGE, MBG_ERR_RANGE }, // 34, Math result too large or too small (not representable). +#if defined( ENODATA ) + { ENODATA, MBG_ERR_NO_DATA }, // 61, No (more) data. +#endif +#if defined( ETIME ) + { ETIME, MBG_ERR_TIMER }, // 62, Timer expired (e.g. stream timeout on USB disconnect). +#endif +#if defined( EOVERFLOW ) + { EOVERFLOW, MBG_ERR_OVERFLOW }, // 75, Value too large for defined data type (can't be stored). +#endif +#if defined( ENOTSOCK ) + { ENOTSOCK, MBG_ERR_NOT_A_SOCKET }, // 88, Socket operation on non-socket (file descriptor is not a socket). +#endif +#if defined( ECONNRESET ) + { ECONNRESET, MBG_ERR_CONN_RESET }, // 104, Connection reset by peer +#endif +#if defined( ETIMEDOUT ) + { ETIMEDOUT, MBG_ERR_TIMEOUT }, // 110, Connection timed out +#endif + { 0, 0 } // end-of-table identifier + +}; // posix_errno_table + +#endif // defined( _MBG_TGT_HAS_POSIX_ERRNO ) + + + +#if defined( _MBG_TGT_HAS_POSIX_H_ERRNO ) + +static ERRNO_CNV_ENTRY posix_h_errno_table[] = +{ + // POSIX codes taken from Linux netdb.h + { HOST_NOT_FOUND, MBG_ERR_HOST_NOT_FOUND }, // The specified host is unknown + // { NO_ADDRESS, }, // Usually same numeric value as NO_DATA + // { NO_DATA, }, // The requested name is valid but does not have an IP address + // { NO_RECOVERY, }, // A nonrecoverable name server error occurred + // { TRY_AGAIN, }, // A temporary error occurred on an authoritative name server. Try again later. + { 0, 0 } // end-of-table identifier + +}; // posix_h_errno_table + +#endif // defined( _MBG_TGT_HAS_POSIX_H_ERRNO ) + + + +#if defined( MBG_TGT_CVI ) + +static ERRNO_CNV_ENTRY cvi_rs232_error_table[] = +{ + // { kRS_UnknownSysError, }, // Unknown system error. + // { kRS_InvalidPortNum, }, // In valid port number. + // { kRS_PortNotOpen, }, // Port is not open. + // { kRS_UnknownIOError, }, // Unknown I/O error. + // { kRS_InternalError, }, // Unexpected internal error. + // { kRS_NoPortFound, }, // No serial port found. + // { kRS_CanNotOpenPort, }, // Cannot open port. + // { kRS_NullPointerPassed, }, // A NULL pointer was passed when a non-NULL pointer was expected. + // { kRS_OutOfMemory, }, // Out of memory. + // { kRS_OutOfSystemResources, }, // Unable to allocate system resources. + // { kRS_InvalidParameter, }, // Invalid parameter. + // { kRS_InvalidBaudRate, }, // Invalid baud rate. + // { kRS_InvalidParity, }, // Invalid parity. + // { kRS_InvalidDataBits, }, // Invalid number of data bits. + // { kRS_InvalidStopBits, }, // Invalid number of stop bits. + // { kRS_BadFileHandle, }, // Bad file handle. + // { kRS_FileIOError, }, // File I/O error. + // { kRS_InvalidCount, }, // Invalid count; must be greater than or equal to 0. + // { kRS_InvalidIntLevel, }, // Invalid interrupt level. + // { kRS_IOTimeOut, }, // I/O operation timed out. + // { kRS_InvalidBreakTime, }, // Break time must be a positive value. + // { kRS_InvalidInQSize, }, // Requested input queue size must be 0 or greater. + // { kRS_InvalidOutQSize, }, // Requested output queue size must be 0 or greater. + // { kRS_GeneralIOFailure, }, // General I/O error. + // { kRS_InvalidBufferPointer, }, // Buffer parameter is NULL. + // { kRS_VISALibrariesMissing, }, // A necessary run-time library could not be found or loaded. + // { kRS_NoAckReceived, }, // Packet was sent, but no acknowledgment was received. + // { kRS_MaxRetriesBeforeSend, }, // Packet was not sent within retry limit. + // { kRS_MaxRetriesBeforeReceived, }, // Packet was not received within retry limit. + // { kRS_UnexpectedEOT, }, // End of transmission character encountered when start of data character expected. + // { kRS_CanNotReadPackNum, }, // Unable to read packet number. + // { kRS_InconsistentPackNum, }, // Inconsistent packet number. + // { kRS_CanNotReadPackData, }, // Unable to read packet data. + // { kRS_CanNotReadCheckSum, }, // Unable to read checksum. + // { kRS_CheckSumError, }, // Checksum received did not match computed checksum. + // { kRS_PackSizeGTInQ, }, // Packet size exceeds input queue size. + // { kRS_OpenFileError, }, // Error opening file. + // { kRS_ReadFileError, }, // Error reading file. + // { kRS_NoInitNegAck, }, // Did not receive initial negative acknowledgment character. + // { kRS_NoAckAfterEOT, }, // Did not receive acknowledgment after end of transmission character was sent. + // { kRS_WriteFileError, }, // Error writing to file. + // { kRS_NoSOHorEOT, }, // Did not receive either a start of data or end of transmission character when expected. + // { kRS_TransferCancelled, }, // Transfer was canceled because CAN ASCII character was received. + // { kRS_InvalidStartDelay, }, // Invalid start delay. + // { kRS_InvalidMaxTries, }, // Invalid maximum number of retries. + // { kRS_InvalidWaitPeriod, }, // Invalid wait period. + // { kRS_InvalidPacketSize, }, // Invalid packet size. + // { kRS_CanNotReadCRC, }, // Unable to read Cyclical Redundancy Check. + // { kRS_CRCError, }, // Cyclical Redundancy Check error. + { 0, 0 } // end-of-table identifier + +}; // cvi_rs232_error_table + +#endif // defined( MBG_TGT_CVI ) + + + +#if defined( MBG_TGT_WIN32 ) + +#if defined( MBG_TGT_KERNEL ) + +/** + * @brief Mappings of some NTSTATUS codes to Meinberg error codes + * + * Kernel space Windows APIs use NTSTATUS codes as return values, + * which consist of several bit fields which also provide some severity + * and facility codes, similar to the message IDs used with text resources. + * The status codes and associated message texts are defined + * in the ntstatus.h file shipped with the various Windows DDKs. + * + * Please note that WIN32 user space API function return a different + * set of error codes on failure. See ::win32_sys_err_table. + * + * @see ::mbg_ioctl_to_ntstatus_table + * @see ::win32_kernel_status_table + * @see ::win32_sys_err_table + * @see ::win32_wsa_err_table + * @see @ref MBG_ERROR_CODES + */ +static ERRNO_CNV_ENTRY win32_kernel_status_table[] = +{ + { STATUS_INVALID_PARAMETER, MBG_ERR_INV_PARM, }, // 0xC000000DL, An invalid parameter was passed to a service or function. + { STATUS_INVALID_DEVICE_REQUEST, MBG_ERR_INV_DEV_REQUEST }, // 0xC0000010L, The specified request is not a valid operation for the target device. + { STATUS_DEVICE_BUSY, MBG_ERR_IRQ_UNSAFE }, // 0x80000011L, The device is currently busy. + { STATUS_NO_MEMORY, MBG_ERR_NO_MEM }, // 0xC0000017L, Not enough memory available to complete the specified operation. + { STATUS_NO_DATA_DETECTED, MBG_ERR_NOT_SUPP_BY_DEV }, // 0x80000022L, (normally used with tape access, but mis-used here) + { STATUS_ACCESS_DENIED, MBG_ERR_PERM }, // 0xC0000022L, A process has requested access to an object, but has not been granted those access rights. + { STATUS_IO_DEVICE_ERROR, MBG_ERR_IO }, // 0xC0000185L, The I/O device reported an I/O error. + + { STATUS_BUFFER_TOO_SMALL, MBG_ERR_BUFFER_TOO_SMALL }, // 0xC0000023L, The buffer is too small to contain the entry. No information has been written to the buffer. + // { STATUS_CANCELLED, }, // 0xC0000120L, The I/O request was canceled. + // { STATUS_DELETE_PENDING, }, // 0xC0000056L, A non close operation has been requested of a file object with a delete pending. + // { STATUS_DEVICE_CONFIGURATION_ERROR, }, // 0xC0000182L, The I/O device is configured incorrectly or the configuration parameters to the driver are incorrect. + { STATUS_DEVICE_NOT_READY, MBG_ERR_NOT_READY }, // 0xC00000A3L, The device (drive) is not ready for use. + // { STATUS_INSUFFICIENT_RESOURCES, }, // 0xC000009AL, Insufficient system resources exist to complete the API. + // { STATUS_MORE_PROCESSING_REQUIRED, }, // 0xC0000016L, The specified IRP cannot be disposed of because the I/O operation is not complete. + // { STATUS_NOT_IMPLEMENTED, }, // 0xC0000002L, The requested operation is not implemented. + // { STATUS_NOT_SUPPORTED, }, // 0xC00000BBL, The network request is not supported. + // { STATUS_NO_SUCH_DEVICE, }, // 0xC000000EL, A device which does not exist was specified. + // { STATUS_OBJECT_NAME_NOT_FOUND, }, // 0xC0000034L, Object Name not found. + // { STATUS_PENDING, }, // 0x00000103L, The operation that was requested is pending completion. + { STATUS_TIMEOUT, MBG_ERR_TIMEOUT }, // 0x00000102L, STATUS_TIMEOUT + // { STATUS_UNSUCCESSFUL, }, // 0xC0000001L, The requested operation was unsuccessful. + { 0, 0 } // end-of-table identifier + +}; // win32_kernel_status_table + + + +#if !_USE_WIN32_PRIVATE_STATUS_CODES + +/** + * @brief Windows IOCTL error conversion table. + * + * The IOCTL handler of a Meinberg kernel driver actually calls + * some Meinberg mbglib functions to access a device, and those + * functions normally return one of the @ref MBG_RETURN_CODES. + * + * However, when the Windows kernel calls the driver's IOCTL handler + * it expects an NTSTATUS code to be returned, so this table can be + * used in an IOCTL handler to map a Meinberg return code to a + * predefined NTSTATUS code that can be returned. + * + * To make things worse, Windows then remaps the NTSTATUS code to one + * of the WIN32 error codes when it passes the IOCTL results up to the + * user space function that submitted the IOCTL request. + * + * The user space function can then convert the returned code back + * to one of the @ref MBG_RETURN_CODES. + * + * For the mapping of NTSTATUS codes to WIN32 error codes + * done by Windows when it passes an IOCTL return code from kernel + * space to user space, see: + * https://support.microsoft.com/en-us/help/113996/info-mapping-nt-status-error-codes-to-win32-error-codes + * + * So care should be taken that the table entries here are defined + * such that in spite of the mnumerous conversions the same error code + * that was returned by a driver function is finally returned by the + * Meinberg user space API call. For example: + * + * - Driver function returns ::MBG_ERR_INV_PARM error. + * + * - Table ::mbg_ioctl_to_ntstatus_table is used to convert this to + * STATUS_INVALID_PARAMETER, which is returned by the IOCTL handler + * in kernel space. + * + * - Windows converts this to ERROR_INVALID_PARAMETER when it passes + * the error code up to user space. + * + * - The user space function uses ::win32_sys_err_table to convert this + * to a Meinberg error code, which again yields ::MBG_ERR_INV_PARM. + * + * @note Eventually it would be possible to defined custom NTSTATUS codes + * in kernel space, e.g. ((NTSTATUS) (0xC0000000 | 0x20000000 | 31)). + * Apparently, such custom error status codes are passed up to user space, + * and GetLastError() after the ioctl() call then returns a negative number, + * i.e. -31 for the example here. + * This had to be tested, though, and could be used to pass Meinberg error + * codes directly up to user space, without the need for a multiple conversion. + * However, there's no guarantee that this always works, and would still + * work in future Windows versions. + * + * @see ::win32_kernel_status_table + * @see ::win32_sys_err_table + * @see ::win32_wsa_err_table + * @see @ref MBG_ERROR_CODES + */ +static ERRNO_CNV_ENTRY mbg_ioctl_to_ntstatus_table[] = +{ + { MBG_ERR_INV_PARM, STATUS_INVALID_PARAMETER }, // ERROR_INVALID_PARAMETER + { MBG_ERR_INV_DEV_REQUEST, STATUS_INVALID_DEVICE_REQUEST }, // ERROR_BAD_COMMAND + { MBG_ERR_IRQ_UNSAFE, STATUS_DEVICE_BUSY }, // ERROR_BUSY + { MBG_ERR_NO_MEM, STATUS_NO_MEMORY }, // ERROR_NOT_ENOUGH_MEMORY + { MBG_ERR_NOT_SUPP_BY_DEV, STATUS_NO_DATA_DETECTED }, // ERROR_NO_DATA_DETECTED (mis-used here) + { MBG_ERR_PERM, STATUS_ACCESS_DENIED }, // ERROR_ACCESS_DENIED + { MBG_ERR_IO, STATUS_IO_DEVICE_ERROR }, // ERROR_IO_DEVICE + { 0, 0 } // end-of-table identifier + +}; // mbg_ioctl_to_ntstatus_table + +#endif // !_USE_WIN32_PRIVATE_STATUS_CODES + + +#else // Windows user space + +/** + * @brief Mappings of WIN32 error codes to Meinberg error codes + * + * If a WIN32 user space API function encounters an error, + * the Windows GetLastError() function has to be called in + * most cases to retrieve an associated error code, which is + * a positive integer number. + * + * Existing error codes and associated message texts + * are defined in the WinError.h file shipped with the + * various SDKs and IDEs. + * + * Please note that Windows socket functions return a different + * set of error codes on failure, and WSAGetLastError() has to + * be called to retrieve the associated error code. + * See ::win32_wsa_err_table. + * + * @see ::win32_wsa_err_table + * @see ::mbg_ioctl_to_ntstatus_table + * @see ::win32_kernel_status_table + * @see @ref MBG_ERROR_CODES + */ +static ERRNO_CNV_ENTRY win32_sys_err_table[] = +{ + // Mappings for some Windows error codes defined in WinError.h + { ERROR_FILE_NOT_FOUND, MBG_ERR_NO_ENTITY }, // 2L: The system cannot find the file specified. + { ERROR_PATH_NOT_FOUND, MBG_ERR_NO_ENTITY }, // 3L: The system cannot find the path specified. + { ERROR_ACCESS_DENIED, MBG_ERR_ACCESS }, // 5L: Access is denied. + { ERROR_INVALID_HANDLE, MBG_ERR_INV_HANDLE }, // 6L: The handle is invalid. + { ERROR_NOT_ENOUGH_MEMORY, MBG_ERR_NO_MEM }, // 8L: Not enough storage is available to process this command. + { ERROR_OUTOFMEMORY, MBG_ERR_NO_MEM }, // 14L: Not enough storage is available to complete this operation. + // { ERROR_WRITE_PROTECT, }, // 19L: The media is write protected. + // { ERROR_BAD_UNIT, }, // 20L: The system cannot find the device specified. + { ERROR_NOT_READY, MBG_ERR_NOT_READY }, // 21L: The device is not ready. + { ERROR_WRITE_FAULT, MBG_ERR_IO }, // 29L: The system cannot write to the specified device. + { ERROR_READ_FAULT, MBG_ERR_IO }, // 30L: The system cannot read from the specified device. + { ERROR_GEN_FAILURE, MBG_ERR_UNSPEC }, // 31L: A device attached to the system is not functioning. + // { ERROR_SHARING_VIOLATION, }, // 32L: The process cannot access the file because it is being used by another process. + // { ERROR_LOCK_VIOLATION, }, // 33L: The process cannot access the file because another process has locked a portion of the file. + // { ERROR_NOT_SUPPORTED, }, // 50L: The request is not supported. + // { ERROR_DUP_NAME, }, // 52L: A duplicate name exists on the network. + // { ERROR_BAD_DEV_TYPE, }, // 66L: The network resource type is not correct. + { ERROR_INVALID_PARAMETER, MBG_ERR_INV_PARM }, // 87L: The parameter is incorrect. + { ERROR_BUFFER_OVERFLOW, MBG_ERR_OVERFLOW }, // 111L: The file name is too long. + { ERROR_INSUFFICIENT_BUFFER, MBG_ERR_BUFFER_TOO_SMALL }, // 122L: The data area passed to a system call is too small. + { ERROR_BUSY, MBG_ERR_BUSY }, // 170L: The requested resource is in use. + // { ERROR_NOACCESS, }, // 998L: Invalid access to memory location. + { ERROR_NO_DATA_DETECTED, MBG_ERR_NOT_SUPP_BY_DEV }, // 1104L: No more data is on the tape. (mis-used here) + { ERROR_IO_DEVICE, MBG_ERR_IO }, // 1117L: The request could not be performed because of an I/O device error. + { ERROR_PRIVILEGE_NOT_HELD, MBG_ERR_PERM }, // 1314L: A required privilege is not held by the client. + { 0, 0 } // end-of-table identifier + +}; // win32_sys_err_table + + + +/** + * @brief Mappings of Winsock error codes to Meinberg error codes + * + * If a Windows socket (Winsock) function encounters an error, + * the Windows WSAGetLastError() function has to be called in + * most cases to retrieve an associated error code, which is + * a positive integer number. + * + * Existing error codes and associated message texts are + * defined in the Winsock2.h file shipped with the various + * SDKs and IDEs. + * + * Please note that the standard WIN32 API functions return a + * different set of error codes on failure, and GetLastError() + * has to be called to retrieve the associated error code. + * See ::win32_err_table. + * + * @see ::win32_sys_err_table + * @see ::mbg_ioctl_to_ntstatus_table + * @see ::win32_kernel_status_table + * @see @ref MBG_ERROR_CODES + */ +static ERRNO_CNV_ENTRY win32_wsa_err_table[] = +{ + { WSAEINTR, MBG_ERR_INTR }, // 10004L A blocking operation was interrupted by a call to WSACancelBlockingCall. + // { WSAEBADF // 10009L The file handle supplied is not valid. + // { WSAEACCES // 10013L An attempt was made to access a socket in a way forbidden by its access permissions. + { WSAEFAULT, MBG_ERR_BAD_ADDRESS }, // 10014L The system detected an invalid pointer address in attempting to use a pointer argument in a call. + { WSAEINVAL, MBG_ERR_INV_PARM }, // 10022L An invalid argument was supplied. + // { WSAEMFILE // 10024L Too many open sockets. + { WSAEWOULDBLOCK, MBG_ERR_AGAIN }, // 10035L A non-blocking socket operation could not be completed immediately. + // { WSAEINPROGRESS // 10036L A blocking operation is currently executing. + // { WSAEALREADY // 10037L An operation was attempted on a non-blocking socket that already had an operation in progress. + { WSAENOTSOCK, MBG_ERR_NOT_A_SOCKET }, // 10038L An operation was attempted on something that is not a socket. + // { WSAEDESTADDRREQ // 10039L A required address was omitted from an operation on a socket. + // { WSAEMSGSIZE // 10040L A message sent on a datagram socket was larger than the internal message buffer or some other network limit, or the buffer used to receive a datagram into was smaller than the datagram itself. + // { WSAEPROTOTYPE // 10041L A protocol was specified in the socket function call that does not support the semantics of the socket type requested. + // { WSAENOPROTOOPT // 10042L An unknown, invalid, or unsupported option or level was specified in a getsockopt or setsockopt call. + // { WSAEPROTONOSUPPORT // 10043L The requested protocol has not been configured into the system, or no implementation for it exists. + // { WSAESOCKTNOSUPPORT // 10044L The support for the specified socket type does not exist in this address family. + // { WSAEOPNOTSUPP // 10045L The attempted operation is not supported for the type of object referenced. + // { WSAEPFNOSUPPORT // 10046L The protocol family has not been configured into the system or no implementation for it exists. + // { WSAEAFNOSUPPORT // 10047L An address incompatible with the requested protocol was used. + // { WSAEADDRINUSE // 10048L Only one usage of each socket address (protocol/network address/port) is normally permitted. + // { WSAEADDRNOTAVAIL // 10049L The requested address is not valid in its context. + // { WSAENETDOWN // 10050L A socket operation encountered a dead network. + // { WSAENETUNREACH // 10051L A socket operation was attempted to an unreachable network. + // { WSAENETRESET // 10052L The connection has been broken due to keep-alive activity detecting a failure while the operation was in progress. + // { WSAECONNABORTED // 10053L An established connection was aborted by the software in your host machine. + { WSAECONNRESET, MBG_ERR_CONN_RESET }, // 10054L An existing connection was forcibly closed by the remote host. + // { WSAENOBUFS // 10055L An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full. + // { WSAEISCONN // 10056L A connect request was made on an already connected socket. + // { WSAENOTCONN // 10057L A request to send or receive data was disallowed because the socket is not connected and (when sending on a datagram socket using a sendto call) no address was supplied. + // { WSAESHUTDOWN // 10058L A request to send or receive data was disallowed because the socket had already been shut down in that direction with a previous shutdown call. + // { WSAETOOMANYREFS // 10059L Too many references to some kernel object. + // { WSAETIMEDOUT // 10060L A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond. + // { WSAECONNREFUSED // 10061L No connection could be made because the target machine actively refused it. + // { WSAELOOP // 10062L Cannot translate name. + // { WSAENAMETOOLONG // 10063L Name component or name was too long. + // { WSAEHOSTDOWN // 10064L A socket operation failed because the destination host was down. + // { WSAEHOSTUNREACH // 10065L A socket operation was attempted to an unreachable host. + // { WSAENOTEMPTY // 10066L Cannot remove a directory that is not empty. + // { WSAEPROCLIM // 10067L A Windows Sockets implementation may have a limit on the number of applications that may use it simultaneously. + // { WSAEUSERS // 10068L Ran out of quota. + // { WSAEDQUOT // 10069L Ran out of disk quota. + // { WSAESTALE // 10070L File handle reference is no longer available. + // { WSAEREMOTE // 10071L Item is not available locally. + // { WSASYSNOTREADY // 10091L WSAStartup cannot function at this time because the underlying system it uses to provide network services is currently unavailable. + // { WSAVERNOTSUPPORTED // 10092L The Windows Sockets version requested is not supported. + { WSANOTINITIALISED, MBG_ERR_SOCK_INIT }, // 10093L Either the application has not called WSAStartup, or WSAStartup failed. + // { WSAEDISCON // 10101L Returned by WSARecv or WSARecvFrom to indicate the remote party has initiated a graceful shutdown sequence. + // { WSAENOMORE // 10102L No more results can be returned by WSALookupServiceNext. + // { WSAECANCELLED // 10103L A call to WSALookupServiceEnd was made while this call was still processing. The call has been canceled. + // { WSAEINVALIDPROCTABLE // 10104L The procedure call table is invalid. + // { WSAEINVALIDPROVIDER // 10105L The requested service provider is invalid. + // { WSAEPROVIDERFAILEDINIT // 10106L The requested service provider could not be loaded or initialized. + // { WSASYSCALLFAILURE // 10107L A system call that should never fail has failed. + // { WSASERVICE_NOT_FOUND // 10108L No such service is known. The service cannot be found in the specified name space. + // { WSATYPE_NOT_FOUND // 10109L The specified class was not found. + // { WSA_E_NO_MORE // 10110L No more results can be returned by WSALookupServiceNext. + // { WSA_E_CANCELLED // 10111L A call to WSALookupServiceEnd was made while this call was still processing. The call has been canceled. + // { WSAEREFUSED // 10112L A database query failed because it was actively refused. + { WSAHOST_NOT_FOUND, MBG_ERR_HOST_NOT_FOUND }, // 11001L No such host is known. + // { WSATRY_AGAIN // 11002L This is usually a temporary error during hostname resolution and means that the local server did not receive a response from an authoritative server. + // { WSANO_RECOVERY // 11003L A non-recoverable error occurred during a database lookup. + // { WSANO_DATA // 11004L The requested name is valid, but no data of the requested type was found. + { 0, 0 } // end-of-table identifier + +}; // win32_wsa_err_table + +#endif // Windows user space + +#endif // defined( MBG_TGT_WIN32 ) + + + +static /*HDR*/ +/** + * @brief Lookup some error code in a conversion table + * + * @param[in] srch_errno The error number to be looked up in the conversion table + * @param[in] tbl A conversion table + * @param[in] dflt_val The code to be returned if no table entry was found. + * + * @return @ref MBG_ERROR_CODES associated with the original error code, + * or @p dflt_val if original code not found in table. + */ +int lookup_tbl_errno( int srch_errno, const ERRNO_CNV_ENTRY tbl[], int dflt_val ) +{ + const ERRNO_CNV_ENTRY *p; + + for ( p = tbl; p->srch_errno || p->mapped_errno; p++ ) + if ( p->srch_errno == srch_errno ) + return p->mapped_errno; + + return dflt_val; + +} // lookup_tbl_errno + + +#if !_USE_WIN32_PRIVATE_STATUS_CODES + +/*HDR*/ +/** + * @brief Convert one of the @ref MBG_ERROR_CODES to an OS-specific format + * + * @param[in] err_no One of the @ref MBG_ERROR_CODES. + * + * @see @ref MBG_ERROR_CODES + * + * @return An OS-specific error code + */ +int mbg_errno_to_os( int err_no ) +{ + #if defined( MBG_TGT_KERNEL ) + + #if defined( MBG_TGT_WIN32 ) + + if ( err_no == MBG_SUCCESS ) + return STATUS_SUCCESS; + + return lookup_tbl_errno( err_no, mbg_ioctl_to_ntstatus_table, STATUS_UNSUCCESSFUL ); + + #elif defined( MBG_TGT_LINUX ) + + #elif defined( MBG_TGT_FREEBSD ) + + #elif defined( MBG_TGT_NETBSD ) + + #else + + #error this needs to be implemented + + #endif + + #else // user space + + #if 0 + #if defined( MBG_TGT_WIN32 ) // FIXME TODO + // Windows uses specially encoded numbers + return ( -err_no | 0xE0000000L ); + + #elif defined( MBG_TGT_BSD ) + + return -err_no; + + #else + + return err_no; + + #endif + #endif // 0 + + #endif + + return err_no; + +} // mbg_errno_to_os + +#endif // _USE_WIN32_PRIVATE_STATUS_CODES + + + +/*HDR*/ +/** + * @brief Return an error string associated with the @ref MBG_ERROR_CODES + * + * @param[in] mbg_errno One of the @ref MBG_ERROR_CODES + * + * @return A constant string describing the error, or NULL for unknown error codes + */ +const char *mbg_strerror( int mbg_errno ) +{ + static const MBG_CODE_NAME_TABLE_ENTRY tbl[] = MBG_ERR_STR_TABLE_ENG; + + const MBG_CODE_NAME_TABLE_ENTRY *p; + + for ( p = tbl; p->name; p++ ) + { + if ( mbg_errno == p->code ) + return p->name; + } + + return "Unknown error"; + +} // mbg_strerror + + + +#if !defined( _MBG_TGT_OMIT_ERR_MSG ) + +/*HDR*/ +/** + * @brief Check if a value is an error code and print an associated error message + * + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES + * @param[in] what A string indicated what failed + * + * @return true if rc represented an error code, and a message has been printed, else false + */ +bool mbg_cond_err_msg( int rc, const char *what ) +{ + return mbg_cond_err_msg_info( rc, what, NULL ); + +} // mbg_cond_err_msg + + + +/*HDR*/ +/** + * @brief Check if a value is an general or a "not supported" error code and print an associated message + * + * If rc contains an error code then an error message is printed, and true is returned. + * + * If the optional parameter string info2 is not NULL then it should contain + * the name of a feature which has been tested before. In this case, if the error + * code is the specific error ::MBG_ERR_NOT_SUPP_BY_DEV then a "not supported" message + * is printed using info2. + * + * If info2 is NULL, or the error code is not ::MBG_ERR_NOT_SUPP_BY_DEV then the standard + * error message is printed anyway. + * + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES + * @param[in] what A string indicated what failed + * @param[in] info An optional informational string telling what is not supported (may be @a NULL). + * + * @return true if rc represented an error code, and a message has been printed, else false + */ +bool mbg_cond_err_msg_info( int rc, const char *what, const char *info ) +{ + if ( mbg_rc_is_error( rc ) ) + { + if ( info && ( rc == MBG_ERR_NOT_SUPP_BY_DEV ) ) + fprintf( stderr, "This device does not %s.\n", info ); + else + fprintf( stderr, "** %s failed: %s (rc: %i)\n", what, mbg_strerror( rc ), rc ); + + return true; + } + + return false; + +} // mbg_cond_err_msg_info + +#endif // !defined( _MBG_TGT_OMIT_ERR_MSG ) + + + +#if defined( MBG_TGT_CVI ) + +/*HDR*/ +/** + * @brief Translate an error code from the Labwindows/CVI RS-232 library to one of the @ref MBG_ERROR_CODES + * + * @param[in] cvi_rc An error code returned by a CVI RS-232 library function + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + * + * @see http://zone.ni.com/reference/en-XX/help/370051V-01/cvi/libref/cvirs232_error_conditions/ + */ +int mbg_cvi_rs232_error_to_mbg( int cvi_rc, const char *info ) +{ + #if DEBUG + if ( info ) + fprintf( stderr, "%s, CVI RS-232 rc: %i\n", info, cvi_rc ); + #else + (void) info; // avoid compiler warning + #endif + + return ( cvi_rc < 0 ) ? lookup_tbl_errno( cvi_rc, cvi_rs232_error_table, MBG_ERR_UNKNOWN ) : MBG_SUCCESS; + +} // mbg_cvi_rs232_error_to_mbg + +#endif + + + +#if defined( MBG_TGT_WIN32 ) + +#if defined( MBG_TGT_KERNEL ) + +/*HDR*/ +/** + * @brief Translate a Windows NTSTATUS code to one of the @ref MBG_ERROR_CODES + * + * @param[in] st One of the NTSTATUS codes defined in ntstatus.h + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_win32_ntstatus_to_mbg( NTSTATUS st, const char *info ) +{ + #if DEBUG + if ( info ) + _mbgddmsg_2( DEBUG, MBG_LOG_INFO, "%s, ntstatus: 0x%08lX\n", info, (long) st ); + #else + (void) info; // avoid compiler warning + #endif + + return lookup_tbl_errno( st, win32_kernel_status_table, MBG_ERR_UNKNOWN ); + +} // mbg_win32_ntstatus_to_mbg + + +#else // Windows user space + +/*HDR*/ +/** + * @brief Translate a Windows non-socket API return code to one of the @ref MBG_RETURN_CODES + * + * @param[in] win32_sys_rc A Windows non-socket API error code as returned by GetLastError(), or ERROR_SUCCESS. + * @param[in] info An optional informational text string, or NULL. + * + * @return One of the @ref MBG_RETURN_CODES + */ +int mbg_win32_sys_err_to_mbg( DWORD win32_sys_rc, const char *info ) +{ + int rc = MBG_SUCCESS; + + if ( win32_sys_rc == ERROR_SUCCESS ) + goto out; + + if ( win32_sys_rc & STATUS_CUSTOM_FLAG_MASK ) + { + // This is a user-defined error code or message ID, e.g. returned by an IOCTL + // call. The lower 16 bits contain the (positive) error code while the upper + // 16 bits contain flags as specified for the Windows API in winerror.h. + // So we assume the error code is just the absolute value of one of the + // @ref MBG_ERROR_CODES, and we return the negated value. + rc = - (int) ( win32_sys_rc & 0xFFFF ); + goto out; + } + +#if 0 // TODO FIXME + rc = (int) win32_sys_rc; + + if ( rc < 0 ) + { + // If the error code is negative then this is a user-defined + // error code e.g. returned by an IOCTL call. In this case we + // assume it's one of the + goto out; + } +#endif + + rc = lookup_tbl_errno( win32_sys_rc, win32_sys_err_table, MBG_ERR_UNKNOWN ); + +out: + #if DEBUG + if ( info ) + fprintf( stderr, "%s, win32_sys_rc: 0x%08lX (%i) --> %i (%s)\n", + info, (long) win32_sys_rc, (int) win32_sys_rc, + rc, mbg_strerror( rc ) ); + #else + (void) info; // avoid compiler warning + #endif + + return rc; + +} // mbg_win32_sys_err_to_mbg + + + +/*HDR*/ +/** + * @brief Translate a Windows socket API error code to one of the @ref MBG_ERROR_CODES + * + * @param[in] wsa_err A Windows socket API error code as returned by WSAGetLastError() + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_win32_wsa_err_to_mbg( int wsa_err, const char *info ) +{ + #if DEBUG + if ( info ) + fprintf( stderr, "%s, wsa_err: %i\n", info, wsa_err ); + #else + (void) info; // avoid compiler warning + #endif + + // The WSA error code is only retrieved after an error has occurred, so + // we don't need care for the success case here. + return lookup_tbl_errno( wsa_err, win32_wsa_err_table, MBG_ERR_UNKNOWN ); + +} // mbg_win32_wsa_err_to_mbg + +#endif // Windows user space + +#endif // defined( MBG_TGT_WIN32 ) + + + + +#if defined( _MBG_TGT_HAS_POSIX_ERRNO ) + +/*HDR*/ +/** + * @brief Translate a POSIX errno error code to one of the @ref MBG_ERROR_CODES + * + * @param[in] posix_errno A POSIX error code as usually defined in errno.h + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_posix_errno_to_mbg( int posix_errno, const char *info ) +{ + #if DEBUG && !defined( MBG_TGT_KERNEL ) + if ( info ) + fprintf( stderr, "%s: %s (errno: %i)\n", info, + strerror( posix_errno ), posix_errno ); + #else + (void) info; // avoid compiler warning + #endif + + return lookup_tbl_errno( posix_errno, posix_errno_table, MBG_ERR_UNKNOWN ); + +} // mbg_posix_errno_to_mbg + +#endif // defined( _MBG_TGT_HAS_POSIX_ERRNO ) + + + +#if defined( _MBG_TGT_HAS_POSIX_H_ERRNO ) + +/*HDR*/ +/** + * @brief Translate a POSIX h_errno error code to one of the @ref MBG_ERROR_CODES + * + * This function is specific to translate error codes returned by + * gethostbyname() and gethostbyaddr(). In case of error these functions + * don't set errno but h_errno to a specific value. + * + * The functions gethostbyname() and gethostbyaddr() are obsolete, + * and getaddressinfo() should be used preferably. + * + * @param[in] posix_h_errno An error code as usually defined in netdb.h + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_posix_h_errno_to_mbg( int posix_h_errno, const char *info ) +{ + #if DEBUG && !defined( MBG_TGT_KERNEL ) + if ( info ) + fprintf( stderr, "%s: %s (h_errno: %i)\n", info, + hstrerror( posix_h_errno ), posix_h_errno ); + #else + (void) info; // avoid compiler warning + #endif + + return lookup_tbl_errno( posix_h_errno, posix_h_errno_table, MBG_ERR_UNKNOWN ); + +} // mbg_posix_h_errno_to_mbg + +#endif // defined( _MBG_TGT_HAS_POSIX_H_ERRNO ) + + + +#if !defined( _MBG_TGT_OMIT_LAST_ERROR ) + +/*HDR*/ +/** + * @brief Get and translate last error after non-socket function call + * + * Retrieve the "last error" code after a non-socket function has been called + * and translate to one of the @ref MBG_ERROR_CODES. + * + * On POSIX systems the "last error" code is always stored in errno, but + * e.g. under Windows the "last error" code after a socket function + * has to be retrieved by calling WSAGetLastError(), whereas the "last error" + * code from non-socket POSIX-like functions has to be retrieved + * by calling GetLastError(). + * + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_get_last_error( const char *info ) +{ + #if defined( MBG_TGT_WIN32 ) + + // Under Windows the "last error" code after a non-socket function + // ("Windows System Errors") has to be retrieved by calling GetLastError(), + // whereas the "last error" code from POSIX-like socket functions + // ("Windows Sockets Error Codes") has to be retrieved by calling + // WSAGetLastError(). + return mbg_win32_sys_err_to_mbg( GetLastError(), info ); + + #elif defined( MBG_TGT_POSIX ) + + // On POSIX systems the "last error" code is always stored in errno. + return mbg_posix_errno_to_mbg( errno, info ); + + #else + + // ### TODO #error This function is not supported for this target. + return mbg_posix_errno_to_mbg( errno, info ); + + #endif + +} // mbg_get_last_error + + + +#if !defined( _MBG_TGT_OMIT_SOCKET_ERRORS ) + +/*HDR*/ +/** + * @brief Get and translate last error after socket function call + * + * Retrieve the "last error" code after a socket function has been called + * and translate to one of the @ref MBG_ERROR_CODES. + * + * On POSIX systems the "last error" code is always stored in errno, but + * e.g. under Windows the "last error" code after a socket function + * has to be retrieved by calling WSAGetLastError, whereas the "last error" + * code from non-socket POSIX-like functions is stored in errno as usual. + * + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_get_last_socket_error( const char *info ) +{ + #if defined( MBG_TGT_CVI ) + + #warning This needs to be implemented for CVI + return MBG_ERR_UNKNOWN; + + #elif defined( MBG_TGT_WIN32 ) + + #if !defined( MBG_TGT_KERNEL ) + // Under Windows the "last error" code after a POSIX-like socket + // function ("Windows Sockets Error Code") has to be retrieved + // by calling WSAGetLastError(), whereas the "last error" code + // after a non-socket function ("Windows System Errors") has + // to be retrieved by calling GetLastError(). + return mbg_win32_wsa_err_to_mbg( WSAGetLastError(), info ); + #else + return MBG_ERR_GENERIC; // TODO should we only work with NTSTATUS codes in kernel mode? + #endif + + #elif defined( MBG_TGT_POSIX ) + + // On POSIX systems the "last error" code is always stored in errno. + return mbg_posix_errno_to_mbg( errno, info ); + + #else + + #error This function is not supported for this target. + + #endif + +} // mbg_get_last_socket_error + + + +/*HDR*/ +/** + * @brief Retrieve and convert last error after gethostbyname() + * + * This function is specific to retrieve and translate error codes + * returned by gethostbyname() and gethostbyaddr(). In case of error + * these functions don't set errno but h_errno on POSIX systems, but + * under Windows the error code can be retrieved by WSAGetLastError() + * as usual. + * + * The functions gethostbyname() and gethostbyaddr() are obsolete, + * and getaddressinfo() should be used preferably. + * + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_get_gethostbyname_error( const char *info ) +{ + #if defined( MBG_TGT_CVI ) + + #warning This needs to be implemented for CVI + return MBG_ERR_UNKNOWN; + + #elif defined( MBG_TGT_WIN32 ) + + #if !defined( MBG_TGT_KERNEL ) + return mbg_win32_wsa_err_to_mbg( WSAGetLastError(), info ); + #else + return MBG_ERR_GENERIC; + #endif + + #elif defined( MBG_TGT_POSIX ) + + return mbg_posix_h_errno_to_mbg( h_errno, info ); + + #else + + #error This function is not supported for this target. + + #endif + +} // mbg_get_gethostbyname_error + +#endif // !defined( _MBG_TGT_OMIT_SOCKET_ERRORS ) + +#endif // !defined( _MBG_TGT_OMIT_LAST_ERROR ) + + + +#if 0 // not yet finished +// error handler for getaddressinfo() +/* + * Handle specific error returned by getaddressinfo() + */ + /*HDR*/ +int mbg_gai_error( int rc, const char *info ) +{ + #if defined( MBG_TGT_CVI ) + + #warning This needs to be implemented for CVI + return MBG_ERR_UNKNOWN; + + #elif defined( MBG_TGT_WIN32 ) + + return mbg_win32_wsa_err_to_mbg( WSAGetLastError(), info ); + + #elif defined( MBG_TGT_POSIX ) + + return mbg_posix_h_errno_to_mbg( h_errno, info ); + + #else + + return MBG_ERR_UNKNOWN; + + #endif + +} // mbg_get_gai_error + +#endif + + + +#if defined( USE_MBG_ZLIB ) + +/*HDR*/ +/** + * @brief Retrieve and convert last zlib internal error code + * + * @param[in] zlib_error zlib internal error code + * @param[in] info An optional informational text string, or NULL + * @param[in] msg An optional zlib specific error msg, or NULL. + * Struct z_stream contains member msg. + * + * @return One of the @ref MBG_ERROR_CODES + */ +int mbg_zlib_error_to_mbg( int zlib_error, const char *info, const char *msg ) +{ + #if DEBUG + if ( info && msg ) + fprintf( stderr, "%s: %s (zlib_error: %d)\n", info, + msg, zlib_error ); + #endif + + switch ( zlib_error ) + { + case Z_ERRNO: return mbg_get_last_error( info ); + case Z_MEM_ERROR: return MBG_ERR_NO_MEM; + /* + * All other zlib error codes are not specified any further. + * So, it's hard to guess what they mean and we return MBG_UNSPEC so far. + */ + default: + return MBG_ERR_UNKNOWN; + } + +} // mbg_zlib_error_to_mbg + +#endif // defined( USE_MBG_ZLIB ) + + diff --git a/c/mbglib/include/cfg_hlp.h b/c/mbglib/include/cfg_hlp.h new file mode 100644 index 0000000..8e11cc5 --- /dev/null +++ b/c/mbglib/include/cfg_hlp.h @@ -0,0 +1,2074 @@ + +/************************************************************************** + * + * $Id: cfg_hlp.h 1.7 2019/09/27 14:24:45Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for configuration programs. + * + * WARNING: Changing the constants defined here affects the size of + * the related structures and arrays, and thus would break compatibility + * if used in DLLs / shared object libraries. + * + * Care must be taken that the number of objects supported by + * any particular device (which can be only determined at runtime) + * does not exceed the max. number of objects specified here + * for the configuration programs. + * + * ----------------------------------------------------------------------- + * $Log: cfg_hlp.h $ + * Revision 1.7 2019/09/27 14:24:45Z martin + * New structure definitions to support new API features. + * Struct names were added by thomas-b to support forward declarations. + * Some new inline functions. + * Updated function prototypes and some doxygen comments. + * Revision 1.6 2018/09/20 11:22:11 martin + * Renamed some global variables to more common names. + * Added string initializer tables and associated macros + * for some PTP configuration stuff. + * Revision 1.5 2018/07/05 10:37:05Z martin + * Renamed setup_port_info_from_port_settings() + * to setup_port_info_from_port_parm(). + * Initializer for OS targets added by philipp. + * Database feature support added by philipp. + * I/O helper structures and API refuctored by philipp. + * Firmware management wrapper structs added by philipp. + * Syslog option added to monitoring feature by philipp. + * Service feature and API added by philipp. + * Return random UID for TLVs under Windows. + * MBG_EVENT stuff integrated with common/general monitoring + * stuff by philipp. + * Monitoring events refactored and tainted config support + * added by philipp. + * Exclude some function from build in kernel mode. + * Fixed build for NetBSD. + * Supporting MBG_TGT_NO_TGT. + * Updated function prototypes. + * Revision 1.4 2017/07/05 13:22:00 martin + * Definitions for TLV, IMS, and GPIO provided by philipp. + * Definitions for ALL_XPB_INFO, ALL_NET_CFG_INFO, + * ALL_PTP_V2_COMMON_DATASETS, ALL_PTP_V1_COMMON_DATASETS, + * ALL_UCAP and associated stuff provided by thomas-b. + * Definitions for xmulti_ref and IO PORT, SNMP and MONITORING, + * and associated stuff provided by philipp and thomas-b. + * New definitions COMP_SIG_MODES and PCPS_TIME_EXT_FLAGS. + * New inline functions device_id_is_serial() and + * device_id_is_lan(). + * Moved inline function num_bits_set() and a lot of + * global configuration variables here. + * Older defines N_SUPP_DEV, PCPS_MAX_DDEVS, and MBG_MAX_DEVICES + * have been obsoleted by new defines N_SUPP_DEV_BUS, N_SUPP_DEV_EXT, + * and N_SUPP_DEV_TOTAL. + * Updated function prototypes. + * Revision 1.3 2013/09/25 10:02:15 martin + * Added ALL_PTP_CFG_INFO, ALL_GNSS_SAT_INFO_IDX and + * related definitions. + * Added doxygen comments. + * Revision 1.2 2012/10/02 18:16:26 martin + * Modified some typedefs to be more compliant with the underlying types. + * Revision 1.1 2011/09/21 15:59:59 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _CFG_HLP_H +#define _CFG_HLP_H + + +/* Other headers to be included */ + +#include <gpsdefs.h> +#include <mbgklist.h> + +#if !defined( MBG_TGT_KERNEL ) + #include <stdlib.h> + #include <string.h> +#endif + +#if defined( _PRELIMINARY_CODE ) + #if defined( MBG_TGT_POSIX ) + #include <sys/stat.h> + #include <time.h> + #endif // MBG_TGT_POSIX + + #if defined( MBG_TGT_LINUX ) + #include <sys/sysinfo.h> + #endif // MBG_TGT_LINUX + +#endif // _PRELIMINARY_CODE + +#ifdef _CFG_HLP + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +#if 1 // ### TODO cleanup + +#define N_SUPP_DEV_BUS 16 +#define N_SUPP_DEV_EXT 1 + +#define N_SUPP_DEV_TOTAL ( N_SUPP_DEV_BUS + N_SUPP_DEV_EXT ) + +typedef struct _DEVICE_INFO +{ + char *hw_id; + char fw_id[100]; + +} DEVICE_INFO; + +_ext DEVICE_INFO device_list[N_SUPP_DEV_TOTAL]; + +#endif + + + +/** + * @defgroup cfg_hlp_com_parm_cnv_fncs Legacy COM_PARM conversion functions + */ + +/// @brief The max number of serial ports supported by configuration programs +#define MAX_PARM_PORT 10 + +/// @brief The max number of serial string types supported by configuration programs +#define MAX_PARM_STR_TYPE 20 + +/// @brief The max number of programmable pulse outputs supported by configuration programs +#define MAX_PARM_POUT 10 + +/// @brief The max number of GNSS settings supported by configuration programs +#define MAX_PARM_GNSS_SAT N_GNSS_TYPES + +/// @brief The max number of PTP unicast masters supported by configuration programs +#define MAX_PARM_PTP_UC_MASTER 3 + +/// @brief The max number of external NTP server associations to be handled by configuration programs +#define MAX_PARM_EXT_NTP_SRVR 20 + +/// @brief The max number of GPIO ports supported by configuration programs +#define MAX_PARM_GPIO 10 + +/// @brief The max number of XMR sources supported by configuration programs +#define MAX_PARM_XMR 10 + +/// @brief The max number of external NTP servers supported by configuration programs +#define MAX_EXT_NTP_SERVERS 20 + +/// @brief The max. number of time monitoring modules supported by configuration programs +/// Each module may support a different number of targets to be monitored. +/// @see ### TODO +#define MAX_MBG_TIME_MON_MODULES 10 + +/// @brief The max. number of time monitoring targets supported by configuration programs +/// This is the sum of all targets from all monitoring modules. +/// @see ### TODO +#define MAX_MBG_TIME_MON_TARGETS 100 + + + +/// @brief An array of configuration settings for all serial ports +typedef PORT_INFO_IDX ALL_PORT_INFO_IDX[MAX_PARM_PORT]; + +/// @brief An array of configuration settings for all serial string types +typedef STR_TYPE_INFO_IDX ALL_STR_TYPE_INFO_IDX[MAX_PARM_STR_TYPE]; + +/** + * @brief All configuration parameters for all serial ports + * + * Used to collect all configuration parameters of a clock's serial ports + * that can be handled by a configuration program. + * + * @see ::RECEIVER_INFO::n_com_ports + * @see ::RECEIVER_INFO::n_str_type + */ +typedef struct +{ + ALL_PORT_INFO_IDX pii; ///< all serial port configuration settings + ALL_STR_TYPE_INFO_IDX stii; ///< all supported serial string types + PORT_PARM tmp_pp; ///< used internally only, for compatibility + +} RECEIVER_PORT_CFG; + + + +/** + * @brief All XBP information of a XBP supporting device + * + * This structure represents a list of connected devices + * + * @see ::GPS_HAS_XBP + */ +typedef struct all_xbp_info_s +{ + XBP_LIMITS limits; + XBP_NODE_LIMITS* node_limits; + XBP_NODE_INFO_IDX* node_infos; +} ALL_XBP_INFO; + + + +/** + * @brief An array of configuration settings for all programmable pulse outputs + * + * Used to collect all configuration parameters of a clock's programmable pulse outputs + * that can be handled by a configuration program. + * + * @see ::RECEIVER_INFO::n_prg_out + */ +typedef POUT_INFO_IDX ALL_POUT_INFO_IDX[MAX_PARM_POUT]; + + + +/** + * @brief All network configuration parameters + * + * Used to collect all configuration parameters for networking + * + * @see ::GPS_HAS_NET_CFG + * @see ::GPS_HAS_LAN_IP4 + */ +typedef struct all_net_cfg_info_s +{ + MBG_NET_GLB_CFG_INFO glb_cfg_info; + MBG_NET_INTF_LINK_INFO_IDX *link_infos; + MBG_NET_INTF_ADDR_INFO_IDX *addr_infos; + MBG_IP_ADDR_IDX *dns_srvrs; + MBG_NET_NAME_IDX *dns_srch_doms; + MBG_NET_INTF_ROUTE_INFO_IDX *route_infos; +} ALL_NET_CFG_INFO; + +typedef ALL_NET_CFG_INFO ALL_NET_STATUS_INFO; + + + +/** + * @brief All SNMP configuration information + * + * Used to collect all configuration parameters for monitoring via SNMP + * Can be used, if ::MBG_MONITORING_TYPE_MSK_SNMP is set in ::MBG_MONITORING_LIMITS::supp_types + * + * @see ::MBG_XFEATURE_MONITORING + */ +typedef struct all_snmp_info_s +{ + MBG_SNMP_GLB_INFO glb_info; + MBG_SNMP_V12_INFO_IDX *v12_infos; + MBG_SNMP_V12_TRAP_INFO_IDX *v12_trap_infos; + MBG_SNMP_V3_INFO_IDX *v3_infos; + MBG_SNMP_V3_TRAP_INFO_IDX *v3_trap_infos; + +} ALL_SNMP_INFO; + + + +/** + * @brief All monitoring event data + * + * Used to collect all event data and group related chunks senseful to a single + * event so all data is in one struct. + */ +typedef struct mbg_event +{ + MBG_MSG_IDX idx; + uint16_t reserved; // for 32 bit alignment + MBG_EVENT_INFO info; + MBG_EVENT_STATUS status; + /* Pointer for 3rd party to connect some data */ + void *backref; + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv or cookie data (if necessary) + * or do other stuff before event gets freed. But NEVER use release + * to free the event itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_event*); + void (*release_backref)(struct mbg_event*); + +} MBG_EVENT; + +typedef struct all_events_s +{ + MBG_EVENT_GLB_INFO glb_info; + MBG_MSG_IDX num_events; + uint16_t reserved; // for 32 bit alignment + MBG_EVENT *events; + +} ALL_EVENTS; + + +/** + * @brief All monitoring syslog data + * + * Used to collect all syslog data. + */ + + +typedef struct mbg_syslog_server +{ + unsigned idx; + MBG_SYSLOG_INFO info; + + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv or cookie data (if necessary) + * or do other stuff before event gets freed. But NEVER use release + * to free the event itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_syslog_server*); + +} MBG_SYSLOG_SERVER; + +typedef struct all_syslog_info_s +{ + MBG_SYSLOG_GLB_INFO glb_info; + MBG_SYSLOG_SERVER *servers; + +} ALL_SYSLOG_INFO; + + +/** + * @brief All monitoring information + * + * Used to collect all configuration parameters for monitoring of a device + * Depending on the ::MBG_MONITORING_LIMITS::supp_types, + * the approriate configurations can be found in the sub structures + * + * @see ::MBG_XFEATURE_MONITORING + */ +typedef struct all_monitoring_info_s +{ + MBG_MONITORING_LIMITS limits; + ALL_SNMP_INFO *all_snmp_info; + ALL_EVENTS *all_events; + ALL_SYSLOG_INFO *all_syslog_info; + +} ALL_MONITORING_INFO; + + + +/// @brief Configuration settings for all unicast master specifications +typedef PTP_UC_MASTER_INFO_IDX ALL_PTP_UC_MASTER_INFO_IDX[MAX_PARM_PTP_UC_MASTER]; + +/** + * @brief All PTP configuration parameters + * + * Used to collect all configuration parameters for a PTP daemon + * that can be handled by a configuration program. + * + * @see ::GPS_HAS_PTP + * @see ::PTP_UC_MASTER_CFG_LIMITS::n_supp_master + */ +typedef struct all_ptp_cfg_info_s +{ + PTP_CFG_INFO ptp_cfg_info; + PTP_UC_MASTER_CFG_LIMITS ptp_uc_master_cfg_limits; + ALL_PTP_UC_MASTER_INFO_IDX all_ptp_uc_master_info_idx; + +} ALL_PTP_CFG_INFO; + + +/** + * @brief All PTP next gen configuration parameters, + * only supported if ::MBG_XFEATURE_PTP_NG is set + */ + +typedef struct mbg_ptp_ng_tstamper +{ + unsigned idx; + MBG_PTP_NG_TSTAMPER_INFO info; + MBG_PTP_NG_TSTAMPER_STATUS status; + MBG_PTP_NG_TSTAMPER_SETTINGS *settings; + + void *priv_data; + void (*release_priv)(struct mbg_ptp_ng_tstamper*); + +} MBG_PTP_NG_TSTAMPER; + + +typedef struct mbg_ptp_ng_instc +{ + MBG_MSG_IDX idx; + uint16_t reserved; // for 32 bit alignment + MBG_PTP_NG_INSTC_INFO info; + MBG_PTP_NG_INSTC_STATUS status; + MBG_PTP_NG_INSTC_PKT_CNTRS cntrs; + MBG_PTP_NG_INSTC_SETTINGS *settings; + const MBG_PTP_NG_TSTAMPER *tstamper; + + MBG_PTP_NG_UC_SLAVE_STATUS *uc_slave_list; + + void *priv_data; + void (*release_priv)(struct mbg_ptp_ng_instc*); + +} MBG_PTP_NG_INSTC; + + +typedef struct mbg_ptp_ng_uc_master +{ + MBG_MSG_IDX idx; + uint16_t reserved; // for 32 bit alignment + MBG_PTP_NG_UC_MASTER_INFO info; + MBG_PTP_NG_UC_MASTER_SETTINGS *settings; + const MBG_PTP_NG_INSTC *instc; + + void *priv_data; + void (*release_priv)(struct mbg_ptp_ng_uc_master*); + +} MBG_PTP_NG_UC_MASTER; + + +typedef struct all_ptp_ng_info_s +{ + MBG_PTP_NG_GLB_INFO glb_info; + + MBG_PTP_NG_TSTAMPER *timestampers; + MBG_PTP_NG_INSTC *instances; + MBG_PTP_NG_UC_MASTER *uc_masters; + +} ALL_PTP_NG_INFO; + + +/** + * @brief All PTPv1 common datasets for a PTP device + * + * Contains one of each common datasets plus one port dataset + * for each port of a device. The number of port datasets is defined + * in the ::MBG_PTP_V1_DEFAULT_DATASET::number_ports field of the + * ::ALL_PTP_V1_COMMON_DATASETS::default_dataset member. + * + * @see ::MBG_PTP_V1_DEFAULT_DATASET + * @see ::MBG_PTP_V1_CURRENT_DATASET + * @see ::MBG_PTP_V1_PARENT_DATASET + * @see ::MBG_PTP_V1_TIME_PROPERTIES_DATASET + * @see ::MBG_PTP_V1_PORT_DATASET_IDX + */ +typedef struct +{ + MBG_PTP_V1_DEFAULT_DATASET default_dataset; + MBG_PTP_V1_CURRENT_DATASET current_dataset; + MBG_PTP_V1_PARENT_DATASET parent_dataset; + MBG_PTP_V1_TIME_PROPERTIES_DATASET time_properties_dataset; + MBG_PTP_V1_PORT_DATASET_IDX *port_datasets; + +} ALL_PTP_V1_COMMON_DATASETS; + + + +/** + * @brief All PTPv2 common datasets for a PTP device + * + * Contains one of each common datasets plus one port dataset + * for each port of a device. The number of port datasets is defined + * in the ::MBG_PTP_V1_DEFAULT_DATASET::number_ports field of the + * ::ALL_PTP_V1_COMMON_DATASETS::default_dataset member. + * + * @see ::MBG_PTP_V2_DEFAULT_DATASET + * @see ::MBG_PTP_V2_CURRENT_DATASET + * @see ::MBG_PTP_V2_PARENT_DATASET + * @see ::MBG_PTP_V2_TIME_PROPERTIES_DATASET + * @see ::MBG_PTP_V2_PORT_DATASET_IDX + */ +typedef struct +{ + MBG_PTP_V2_DEFAULT_DATASET default_dataset; + MBG_PTP_V2_CURRENT_DATASET current_dataset; + MBG_PTP_V2_PARENT_DATASET parent_dataset; + MBG_PTP_V2_TIME_PROPERTIES_DATASET time_properties_dataset; + MBG_PTP_V2_PORT_DATASET_IDX *port_datasets; + +} ALL_PTP_V2_COMMON_DATASETS; + + + +typedef struct mbg_sys_ref_src +{ + unsigned idx; + struct mbg_klist_head head; + MBG_SYS_REF_SRC_INFO info; + MBG_SYS_REF_SRC_STATUS status; + MBG_SYS_REF_SRC_SETTINGS *settings; + + void *priv_data; + void (*release_priv)(struct mbg_sys_ref_src*); + +} MBG_SYS_REF_SRC; + + +typedef struct all_sys_ref_info_s +{ + MBG_SYS_REF_LIMITS limits; + MBG_SYS_REF_GLB_STATUS glb_status; + struct mbg_klist_head sources; + const MBG_SYS_REF_SRC *cur_master; + void (*free_source)(MBG_SYS_REF_SRC*); + +} ALL_SYS_REF_INFO; + + + +/** + * @brief An array of configuration settings for all programmable pulse outputs + * + * Used to collect all configuration parameters of a clock's programmable pulse outputs + * that can be handled by a configuration program. + */ +typedef GNSS_SAT_INFO_IDX ALL_GNSS_SAT_INFO_IDX[MAX_PARM_GNSS_SAT]; + + + +/** + * @brief Summary information on all supported GNSS systems + * + * Used to collect all configuration parameters even for devices + * that can receive the signals from multiple satellite systems. + */ +typedef struct all_gnss_info_s +{ + STAT_INFO stat_info; + int n_gnss_supp; + MBG_GNSS_MODE_INFO gnss_mode_info; + ALL_GNSS_SAT_INFO_IDX gnss_sat_info_idx; + +} ALL_GNSS_INFO; + + + +/// @brief Configuration settings for all NTP server associations +typedef NTP_PEER_SETTINGS ALL_NTP_PEER_SETTINGS[MAX_EXT_NTP_SERVERS]; + +/** + * @brief All NTP configuration parameters + * + * Used to collect all configuration parameters for an NTP daemon + * that can be handled by a configuration program. + * + * @see ::GPS_HAS_NTP + */ +typedef struct +{ + ALL_NTP_PEER_SETTINGS all_ntp_peer_settings; + +} NTP_CLIENT_CFG_PEER_SETTINGS; + + +typedef struct all_ntp_cfg_info_s +{ + NTP_GLB_INFO glb_info; + NTP_SYMM_KEY_LIMITS *symm_key_limits; + NTP_SYMM_KEY_INFO_IDX *symm_key_info_idx; + NTP_TRUSTED_KEY_INFO_IDX *trusted_key_info_idx; + + NTP_CLNT_MODE_INFO *clnt_info; + NTP_PEER_SETTINGS_IDX *peer_settings_idx; + + NTP_SRV_MODE_INFO *srv_info; + NTP_REFCLK_CFG_INFO_IDX *refclk_info_idx; + NTP_MISC_LIMITS *misc_limits; + NTP_MISC_ORPHAN_MODE_INFO *orphan_mode_info; + +} ALL_NTP_CFG_INFO; + + +typedef struct all_ntp_status_s +{ + NTP_SYS_STATE sys_state; + NTP_REFCLK_STATE_IDX *refclk_states; + NTP_PEER_STATE_IDX *peer_states; +} ALL_NTP_STATUS; + + + +/// @brief Configuration settings for all GPIO ports +typedef MBG_GPIO_INFO_IDX ALL_GPIO_INFO_IDX[MAX_PARM_GPIO]; + +/// @brief Status information on all GPIO ports +typedef MBG_GPIO_STATUS_IDX ALL_GPIO_STATUS_IDX[MAX_PARM_GPIO]; + + + + +/// @brief Status of all XMR inputs +typedef XMULTI_REF_STATUS_IDX ALL_XMULTI_REF_STATUS_IDX[MAX_PARM_XMR]; + +/// @brief Configuration settings for all XMR inputs +typedef XMULTI_REF_INFO_IDX ALL_XMULTI_REF_INFO_IDX[MAX_PARM_XMR]; + + + +typedef struct all_xmulti_ref_info_s +{ + XMULTI_REF_INSTANCES instances; + XMULTI_EXT_REF_INSTANCES ext_instances; + XMULTI_REF_INFO_IDX *infos; + XMR_EXT_SRC_INFO_IDX *ext_src_infos; + XMR_QL_LIMITS ql_limits; + XMR_QL_SETTINGS_IDX *ql_settings; + /* + * ALL_XMULTI_REF_INFO related flag if at least one ref type supports metrics + * and thus QL stuff! + */ + unsigned has_metrics; +} ALL_XMULTI_REF_INFO; + + +typedef struct all_xmulti_ref_status_s +{ + XMULTI_REF_STATUS_IDX *status; + XMR_HOLDOVER_STATUS *holdover_status; + XMR_STATS_IDX *stats_idx; + XMR_METRICS_IDX *metrics_idx; + /* ALL_XMULTI_REF_STATUS related flag if at least one ref type supports stats */ + unsigned char has_stats; + /* ALL_XMULTI_REF_STATUS related flag if at least one ref type supports metrics */ + unsigned char has_metrics; +} ALL_XMULTI_REF_STATUS; + + + +typedef struct all_ims_info_s +{ + MBG_IMS_STATE state; + MBG_IMS_FDM_INFO *fdm_info; + MBG_IMS_FDM_LIMITS *fdm_limits; + MBG_IMS_FDM_OUTPUT_INFO_IDX *fdm_outinfo_idx; +} ALL_IMS_INFO; + + +typedef struct all_ims_state_s +{ + MBG_IMS_SENSOR_STATE_IDX *sensor_state_idx; + MBG_IMS_FDM_STATE *fdm_state; + MBG_IMS_FDM_OUTPUT_STATE_IDX *fdm_output_state_idx; +} ALL_IMS_STATE; + + + +typedef struct all_gpio_info_s +{ + MBG_GPIO_CFG_LIMITS cfg_limits; + MBG_GPIO_INFO_IDX *infos; +} ALL_GPIO_INFO; + + +typedef struct all_gpio_state_s +{ + MBG_GPIO_STATUS_IDX *states; +} ALL_GPIO_STATE; + + +typedef struct mbg_io_port +{ + unsigned idx; + MBG_IO_PORT_INFO p_info; + MBG_IO_PORT_STATUS status; + MBG_IO_PORT_TYPE_INFO *pt_infos; + /* Shortcut to settings in p_info */ + MBG_IO_PORT_SETTINGS *setts; + void *priv_data; + void (*free_priv_data)(const struct mbg_io_port*, void*); +} MBG_IO_PORT; + + +typedef struct all_mbg_io_ports_s +{ + MBG_IO_PORT_LIMITS limits; + unsigned num_ports; + MBG_IO_PORT *ports; +} ALL_MBG_IO_PORTS; + + +#ifndef MAX_UCAP_ENTRIES +/* + * According to Andre's GPS firmware this is the maximum + * number of user captures that are preserved. + */ +#define MAX_UCAP_ENTRIES 585 +#endif + +typedef struct +{ + struct mbg_klist_head head; + TTM ttm; +} UCAP_ENTRY; + +typedef struct all_ucap_info_s +{ + uint32_t num_ucaps; /// User capture counter, see ::MAX_UCAP_ENTRIES + struct mbg_klist_head list; +} ALL_UCAP_INFO; + +// User Captures via Network configuration, see ::MBG_XFEATURE_UCAP_NET +typedef struct all_ucap_net_info_s +{ + MBG_UCAP_NET_GLB_INFO glb_info; + MBG_UCAP_NET_RECV_INFO_IDX *recv_infos; +} ALL_UCAP_NET_INFO; + + +typedef struct mbg_user +{ + unsigned idx; + MBG_USER_INFO info; + MBG_USER_STATUS status; + + char salt[9]; + + /* Pointer for 3rd party to connect some data */ + void *backref; + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv or cookie data (if necessary) + * or do other stuff before user gets freed. But NEVER use release + * to free the user itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_user*); + void (*release_backref)(struct mbg_user*); + +} MBG_USER; + +typedef struct all_user_info_s +{ + MBG_USER_MNGMNT_INFO user_mngmnt_info; + MBG_USER *users; ///< system users for internal authentication + MBG_USER *user_levels; ///< global user levels for external authentication (i.e. radius/tacacs+) + +} ALL_USER_INFO; + + +typedef struct mbg_service +{ + unsigned idx; + MBG_SERVICE_INFO info; + MBG_SERVICE_STATUS status; + + /* Pointer for 3rd party to connect some data */ + void *backref; + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv or cookie data (if necessary) + * or do other stuff before service gets freed. But NEVER use release + * to free the service itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_service*); + void (*release_backref)(struct mbg_service*); + +} MBG_SERVICE; + +typedef struct all_service_info_s +{ + MBG_SERVICE_MGMT_INFO mgmt_info; + MBG_SERVICE *svcs; + +} ALL_SERVICE_INFO; + + +struct mbg_firmware; +struct mbg_firmware_ufu; + + +typedef struct mbg_firmware +{ + unsigned idx; + MBG_FW_INFO info; + struct mbg_firmware_ufu *ufus; ///< Array of ::MBG_FW_INFO::num_ufus + + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv or cookie data (if necessary) + * or do other stuff before firmware gets freed. But NEVER use release + * to free the firmware itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_firmware*); + +} MBG_FIRMWARE; + + +typedef struct mbg_firmware_ufu +{ + unsigned idx; + MBG_FW_UFU_INFO info; + const struct mbg_firmware *firmware; ///< Backref to firmware + + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + /* + * Can be used to free/release priv data (if necessary) + * or do other stuff before ufu gets freed. But NEVER use release + * to free the ufu itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_firmware_ufu*); + +} MBG_FIRMWARE_UFU; + + +typedef struct all_firmware_info_s +{ + MBG_FW_GLB_INFO glb_info; + MBG_FIRMWARE *firmwares; /// Array of ::MBG_FW_GLB_INFO::installed_fws + +} ALL_FIRMWARE_INFO; + + +typedef struct mbg_database +{ + unsigned idx; + MBG_DATABASE_INFO info; + + /* Pointer for the mallocer to connect some private data */ + void *priv_data; + + /* + * Can be used to free/release priv data (if necessary) + * or do other stuff before ufu gets freed. But NEVER use release + * to free the ufu itself!! This is done by the API right after calling + * release. + */ + void (*release_priv)(struct mbg_database*); + +} MBG_DATABASE; + + +typedef struct all_database_info_s +{ + MBG_DATABASE_GLB_INFO glb_info; + /// Array of ::MBG_DATABASE_GLB_INFO::num_dbs. Yes, until num_dbs!! + /// Databases might have different features and flags set, + /// thus query all info. + MBG_DATABASE *dbs; + +} ALL_DATABASE_INFO; + + +typedef struct +{ + unsigned codec; + const char *products; + +} MBG_EXT_SYS_INFO_CPU_CODEC; + +/// Do not access array via ::MBG_EXT_SYS_INFO_CPUS enum. +/// Only use it as lookup table. Initializer for ::MBG_EXT_SYS_INFO_CPU_CODEC. +#define MBG_EXT_SYS_INFO_CPU_CODECS \ +{ \ + {HPS_USB_HOST_G1_V0, "microSync HSXXX"}, \ + {HPS_USB_DEVICE_G1_V0, "HPS100"}, \ + {HPS_USB_DEVICE_G1_V1, "SSP100"}, \ + {MSSB_USB_HOST_G1_V0, "microSyncHR, microSyncRX"} \ +} + + +/** + * @brief A mode specifying how to interpret a ::PCPS_SIG_VAL + * + * Used with ::PCPS_TIME_EXT::comp_sig_mode. Depending on this mode + * a signal value can be interpreted e.g. as signal strength (with + * long wave or IRIG time code receivers), or as indicator whether an + * antenna is connected (satellite receivers), or a network link is + * available (PTP slaves) or not, and an appropriate status message + * can be displayed. + * + * @see @ref PCPS_SIG_VAL_DEFS + */ +enum COMP_SIG_MODES +{ + COMP_SIG_MODE_NONE, ///< signal value not used + COMP_SIG_MODE_SIGNAL, ///< input signal strength + COMP_SIG_MODE_ANT_CONN, ///< antenna connection state + COMP_SIG_MODE_PORT_LINK, ///< port link state + N_CONN_SIG_MODES +}; + + +/** + * @brief Flag bits indicating if some extended status is available + * + * @see ::PCPS_TIME_EXT_FLAGS + */ +enum PCPS_TIME_EXT_FLAG_BITS +{ + PCPS_TIME_EXT_FLAG_BIT_UTC_VALID, ///< ::PCPS_TIME_EXT::utc_offs field is valid + N_PCPS_TIME_EXT_FLAG_BITS +}; + + +/** + * @brief Flag masks used with ::PCPS_TIME_EXT::flags + * + * @see ::PCPS_TIME_EXT_FLAG_BITS + */ +enum PCPS_TIME_EXT_FLAGS +{ + PCPS_TIME_EXT_FLAG_UTC_VALID = ( 1UL << PCPS_TIME_EXT_FLAG_BIT_UTC_VALID ) ///< see ::PCPS_TIME_EXT_FLAG_BIT_UTC_VALID +}; + + + +_ext BAUD_RATE mbg_baud_rates[N_MBG_BAUD_RATES] +#ifdef _DO_INIT + = MBG_BAUD_RATES +#endif +; + +_ext const char *mbg_baud_rate_strs[N_MBG_BAUD_RATES] +#ifdef _DO_INIT + = MBG_BAUD_STRS +#endif +; + +_ext const char *mbg_framing_strs[N_MBG_FRAMINGS] +#ifdef _DO_INIT + = MBG_FRAMING_STRS +#endif +; + +_ext const char *str_unknown +#ifdef _DO_INIT + = "unknown" +#endif +; + + +_ext const char *str_undefined +#ifdef _DO_INIT + = "(undefined)" +#endif +; + + +_ext const char *str_not_spc +#ifdef _DO_INIT + = "not " +#endif +; + + + +//### TODO +#define DEFAULT_MAX_STR_TYPE 2 // DEFAULT_N_STR_TYPE_GPS ? + +_ext STR_TYPE_INFO default_str_type_info[DEFAULT_MAX_STR_TYPE] +#ifdef _DO_INIT + = { + { DEFAULT_STR_MODES, "Default Time String", "Time", 0 }, + { DEFAULT_STR_MODES_UCAP, "Capture String", "Cap", 0 } + } +#endif +; + + + +_ext const char *mbg_gpio_type_names[N_MBG_GPIO_TYPES] +#ifdef _DO_INIT + = DEFAULT_GPIO_TYPES_SHORT_STRS +#endif +; + +#define _get_gpio_type_name( _i ) \ + ( ( (_i) < N_MBG_GPIO_TYPES ) ? mbg_gpio_type_names[_i] : str_unknown ) + + + +_ext const char *mbg_gpio_port_state_names[N_MBG_GPIO_PORT_STATES] +#ifdef _DO_INIT + = DEFAULT_GPIO_PORT_STATE_NAMES +#endif +; + +#define _get_gpio_port_state_name( _i ) \ + ( ( (_i) < N_MBG_GPIO_PORT_STATES ) ? mbg_gpio_port_state_names[_i] : str_unknown ) + + + +_ext const char *mbg_gpio_signal_shape_names[N_MBG_GPIO_SIGNAL_SHAPES] +#ifdef _DO_INIT + = DEFAULT_GPIO_SIGNAL_SHAPE_NAMES +#endif +; + +#define _get_gpio_signal_shape_name( _i ) \ + ( ( (_i) < N_MBG_GPIO_SIGNAL_SHAPES ) ? mbg_gpio_signal_shape_names[_i] : str_unknown ) + + + +_ext const char *mbg_gpio_fixed_freq_strs[N_MBG_GPIO_FIXED_FREQ] +#ifdef _DO_INIT + = MBG_GPIO_FIXED_FREQ_STRS +#endif +; + +#define _get_gpio_fixed_freq_str( _i ) \ + ( ( (_i) < N_MBG_GPIO_FIXED_FREQ ) ? mbg_gpio_fixed_freq_strs[_i] : str_unknown ) + + + +_ext const char *xmr_holdover_status_mode_names[N_XMR_HOLDOVER_STATUS_MODES] +#ifdef _DO_INIT + = XMR_HOLDOVER_STATUS_MODE_NAMES +#endif +; + +#define _get_xmr_holdover_status_mode_name( _i ) \ + ( ( (_i) < N_XMR_HOLDOVER_STATUS_MODES ) ? xmr_holdover_status_mode_names[_i] : str_unknown ) + + + +_ext const char *ptp_role_strs[N_PTP_ROLES] +#ifdef _DO_INIT + = PTP_ROLE_STRS +#endif +; + +#define _get_ptp_role_str_dflt( _i, _dflt ) \ + ( ( (_i) < N_PTP_ROLES ) ? ptp_role_strs[_i] : _dflt ) + +#define _get_ptp_role_str( _i ) \ + _get_ptp_role_str_dflt( _i, str_unknown ) + + + +_ext const char *ptp_nw_protocol_strs[N_PTP_NW_PROT] +#ifdef _DO_INIT + = PTP_NW_PROT_STRS +#endif +; + +#define _get_ptp_nw_protocol_str_dflt( _i, _dflt ) \ + ( ( (_i) < N_PTP_NW_PROT ) ? ptp_nw_protocol_strs[_i] : _dflt ) + +#define _get_ptp_nw_protocol_str( _i ) \ + _get_ptp_nw_protocol_str_dflt(_i, str_unknown ) + + + +_ext const char *ptp_port_state_strs[N_PTP_PORT_STATE] +#ifdef _DO_INIT + = PTP_PORT_STATE_STRS +#endif +; + +#define _get_ptp_port_state_str_dflt( _i, _dflt ) \ + ( ( (_i) < N_PTP_PORT_STATE ) ? ptp_port_state_strs[_i] : _dflt ) + +#define _get_ptp_port_state_str( _i ) \ + _get_ptp_port_state_str_dflt( _i, str_unknown ) + + + +_ext const char *ptp_clock_accuracy_strs[N_PTP_CLOCK_ACCURACY - PTP_CLOCK_ACCURACY_NUM_BIAS] +#ifdef _DO_INIT + = PTP_CLOCK_ACCURACY_STRS +#endif +; + +#define _get_ptp_clock_accuracy_str_dflt( _i, _dflt ) \ + ( ( ( (_i) >= PTP_CLOCK_ACCURACY_NUM_BIAS ) && ( (_i) < N_PTP_CLOCK_ACCURACY ) ) ? \ + ptp_clock_accuracy_strs[(_i) - PTP_CLOCK_ACCURACY_NUM_BIAS] : _dflt ) + +#define _get_ptp_clock_accuracy_str( _i ) \ + _get_ptp_clock_accuracy_str( _i, str_unknown ) + + + +_ext const char *ptp_delay_mechanism_strs[N_PTP_DELAY_MECH] +#ifdef _DO_INIT + = PTP_DELAY_MECH_NAMES +#endif +; + +#define _get_ptp_delay_mechanism_str_dflt( _i, _dflt ) \ + ( ( (_i) < N_PTP_DELAY_MECH ) ? ptp_delay_mechanism_strs[_i] : _dflt ) + +#define _get_ptp_delay_mechanism_str( _i ) \ + _get_ptp_delay_mechanism_str_dflt( _i, str_unknown ) + + + + +// Terminated by { 0, NULL } +_ext const PTP_TABLE ptp_time_source_table[] +#ifdef _DO_INIT + = PTP_TIME_SOURCE_TABLE +#endif +; + + + +/** + * @brief A structure which holds all satellite info read from a device + * + * @note The structure contains pointers to allocated memory, + * so it can ***not*** be used to exchange data between + * different programs or devices. + * + * @see ::mbgextio_get_all_gnss_sv_info + */ +typedef struct ALL_GNSS_SV_INFO_s +{ + uint16_t n_gnss_sv_stati; // Number of ::GNSS_SV_STATUS_IDX that can be read (if > 0, no ::SV_INFO can be read) + uint16_t n_sv_infos; // Number of ::SV_INFO that can be read + + GNSS_SV_STATUS_IDX *gnss_sv_stati; + SV_INFO *sv_infos; + +} ALL_GNSS_SV_INFO; + + + +/** + * @brief Count the number of bits which are not 0 + * + * @param[in] val Value to be tested + * + * @return The number of non-zero bits in val + */ +static __mbg_inline /*HDR*/ +int num_bits_set( long val ) +{ + int bits_set = 0; + size_t i; + + for ( i = 0; i < ( 8 * sizeof( val ) ); i++ ) + { + if ( val & 1 ) + bits_set++; + + val >>= 1; + } + + return bits_set; + +} // num_bits_set + + + +static __mbg_inline /*HDR*/ +/** + * @brief Compute the value of 2 to the power of n. + * + * In the special case of a base 2 and a small exponent n + * the function pow( base, n ) can simply be replaced by + * a shift operation which executes ***very*** much faster + * than the floating point pow() function. + * In addition this avoids the requirement of explicitly + * linking against the math library. + * + * Please note that if the result is a 32 bit type then @p exp + * must be less than 32. + * @param[in] exp The number of which to compute pow( 2, n ). + * + * @return The result as integer. + */ +uint32_t uint32_pow2( int exp ) +{ + return 1 << exp; + +} // uint32_pow2 + + + +static __mbg_inline /*HDR*/ +/** + * @brief Compute the number of values to be used for PTP lucky packet median filtering. + * + * This only makes sense if the sync interval is negative, + * and below a certain limit, e.g. < -3. + * + * @param[in] ln_sync_intv The sync_intv parameter from a PTP configuration. + * + * @return The result as integer. + */ +int lucky_packet_median_nvals( int8_t ln_sync_intv ) +{ + // For example, if ln_sync_interval is -4 then pow( 2, 4 ) == 16, and the + // the expected number of samples for the lucky packet median filter is 15. + return uint32_pow2( -ln_sync_intv ) - 1; + +} // lucky_packet_median_nvals + + + +#if !defined( MBG_TGT_KERNEL ) + +/** + * @brief Check if a device ID refers to a serial port + * + * @param[in] dev_id A string with the device name or port name + * + * @see ::DEFAULT_SERIAL_DEVICE_NAME + * + * @return true if the device id contains the name of a serial port, else false + */ +static __mbg_inline /*HDR*/ +bool device_id_is_serial( const char *dev_id ) +{ + #if defined( MBG_TGT_NO_TGT ) + return false; //### FIXME + #elif defined( MBG_TGT_WIN32 ) + //##++++ There may be also serial ports under Windows + // which don't have "COM" in their name. + return strstr( dev_id, "COM" ) != NULL; + #elif defined( MBG_TGT_LINUX ) + return strstr( dev_id, "/dev/ttyS" ) != NULL // standard serial device + || strstr( dev_id, "/dev/ttyUSB" ) != NULL; // serial-to-USB adapter + #elif defined( MBG_TGT_FREEBSD ) + return strstr( dev_id, "/dev/ttyu" ) != NULL // dial-in device (standard), FreeBSD 10 and newer + || strstr( dev_id, "/dev/cuau" ) != NULL // dial out device, FreeBSD 10 and newer + || strstr( dev_id, "/dev/ttyd" ) != NULL // dial-in device (standard), before FreeBSD 10 + || strstr( dev_id, "/dev/cuad" ) != NULL; // dial-out device, before FreeBSD 10 + #elif defined( MBG_TGT_NETBSD ) + // TODO This is just an ugly hack which identifies + // some traditional device names as serial ports. + // There are quite a few other possible names. + // See "man 4 com" and "man 4 tty". + return strstr( dev_id, "/dev/tty0" ) != NULL // traditional dial-in devices + || strstr( dev_id, "/dev/dty0" ) != NULL; // traditional dial-out devices + #elif defined( MBG_TGT_QNX_NTO ) + return strstr( dev_id, "/dev/ser" ) != NULL; + #elif defined( MBG_TGT_DOS ) + return strstr( dev_id, "COM" ) != NULL; + #else + #error device_id_is_serial() needs to be implemented for this platform + #endif + +} // device_id_is_serial + + + +/** + * @brief Check if a device ID refers to a LAN connection + * + * @param[in] dev_id A string with the device ID + * + * @return true if the device id specifies a LAN connection, else false + */ +static __mbg_inline /*HDR*/ +bool device_id_is_lan( const char *dev_id ) +{ + return strstr( dev_id, "LAN" ) != NULL; + +} // device_id_is_lan + +#endif // !defined( MBG_TGT_KERNEL ) + + + +#if defined( _PRELIMINARY_CODE ) + +static __mbg_inline /*HDR*/ +MBG_TLV_UID mbg_tlv_create_id( void ) +{ +#if defined( MBG_TGT_LINUX ) ///### FIXME for FreeBSD and Windows + struct sysinfo info; + + // Linux specific, implement Windows equivalent + sysinfo( &info ); + return ( (MBG_TLV_UID) ( ( time( NULL ) >> 16 ) | ( info.uptime << 16 ) ) ); +#else + return rand(); +#endif +} // mbg_tlv_create_id + +#endif // defined( _PRELIMINARY_CODE ) + + + +#if !defined( MBG_TGT_KERNEL ) + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @brief Check if a software revision name should be displayed. + * + * The software revision name is usually empty, except if the + * firmware is a customized version, in which case the field + * contains an identifier string. + * + * There are some standard firmware versions where this string + * is not empty but padded with spaces, etc., so we try to + * clean this up, so it can be displayed appropriately. + * + * @param[in,out] p The ::SW_REV name to check. + * @param[in] verbose The app's verbosity level. + * + * @return != 0 if SW name should be displayed. + */ + int chk_sw_rev_name( SW_REV *p, int verbose ) ; + + /** + * @brief Search a string table for a specific string. + * + * @param[in] search The string to be searched for in table @a str_table. + * @param[in] str_table A table of strings like 'const char *strs[N_STRS]'. + * @param[in] n_entries The number of strings in table @a str_table. + * + * @return The index number of the string table entry matching the @a search string, + * or -1 if the @a search string could not be found. + */ + int get_str_idx( const char *search, const char *str_table[], int n_entries ) ; + + /** + * @brief Search the ::mbg_baud_rates table for a specific baud rate. + * + * @param[in] baud_rate The baud_rate to be searched for. + * + * @return The index number of the specific @a baud_rate in table ::mbg_baud_rates, + * or -1 if the specific @a baud_rate could not be found. + */ + int get_baud_rate_idx( BAUD_RATE baud_rate ) ; + + /** + * @brief Search the ::mbg_framing_strs table for a specific framing string. + * + * @param[in] framing The framing string to be searched for, e.g. "8N1". + * + * @return The index number of the specific @a framing in table ::mbg_framing_strs, + * or -1 if the specific @a framing could not be found. + */ + int get_framing_idx( const char *framing ) ; + + /** + * @brief Convert ::PORT_PARM::mode to ::PORT_SETTINGS::mode + * + * This function is used to evaluate the code from a @a mode field of a legacy + * ::PORT_PARM structure and set up the appropriate fields in a ::PORT_SETTINGS + * structure. + * + * @param[out] p_ps Pointer to a ::PORT_SETTINGS structure to be updated. + * @param[in] pp_mode The mode code from a ::PORT_PARM structure, see ::LGCY_STR_MODES. + * @param[in] cap_str_idx The capture string index number for the case that @a pp_mode is + * a capture string mode. Usually 1 for legacy devices. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_parm_mode_from_port_settings (the complementary function) + * @see ::port_settings_from_port_parm + */ + void port_settings_from_port_parm_mode( PORT_SETTINGS *p_ps, uint8_t pp_mode, int cap_str_idx ) ; + + /** + * @brief Convert a ::PORT_SETTINGS::mode to a legacy ::PORT_PARM::mode + * + * This function is used to derive a a legacy ::PORT_PARM::mode value + * from a ::PORT_SETTINGS structure. + * + * @param[out] pp_mode Pointer to a ::PORT_PARM::mode variable to be updated. + * @param[in] p_ps Pointer to a ::PORT_SETTINGS structure to be evaluated. + * @param[in] cap_str_idx The capture string index number for legacy devices, which is usually 1. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_settings_from_port_parm_mode (the complementary function) + * @see ::port_parm_from_port_settings + */ + void port_parm_mode_from_port_settings( uint8_t *pp_mode, const PORT_SETTINGS *p_ps, int cap_str_idx ) ; + + /** + * @brief Set up a ::PORT_SETTINGS structure from a legacy ::PORT_PARM structure. + * + * @param[out] p_ps Pointer to a ::PORT_SETTINGS structure to be updated. + * @param[in] port_idx Index number of the port settings to be converted. + * @param[in] p_pp The ::PORT_PARM structure to be evaluated, contains settings for 2 ports. + * @param[in] cap_str_idx The capture string index number for legacy devices, which is usually 1. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_parm_from_port_settings (the complementary function) + * @see ::port_settings_from_port_parm_mode + */ + void port_settings_from_port_parm( PORT_SETTINGS *p_ps, int port_idx, const PORT_PARM *p_pp, int cap_str_idx ) ; + + /** + * @brief Set up a a legacy ::PORT_PARM structure from a ::PORT_SETTINGS structure. + * + * @param[out] p_pp Pointer to a ::PORT_PARM structure to be updated. + * @param[in] port_idx Index number of the port settings to be converted. + * @param[out] p_ps Pointer to a ::PORT_SETTINGS structure to be updated. + * @param[in] cap_str_idx The capture string index number for legacy devices, which is usually 1. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::port_settings_from_port_parm (the complementary function) + * @see ::port_parm_mode_from_port_settings + */ + void port_parm_from_port_settings( PORT_PARM *p_pp, int port_idx, const PORT_SETTINGS *p_ps, int cap_str_idx ) ; + + /** + * @brief Check if all serial port capabilities reported by a device are supported by the current driver. + * + * @param[in] p_pi Address of a ::PORT_INFO structure to be checked. + * @param[out] str_type_info_idx An array of ::STR_TYPE_INFO_IDX structures supported by the device + * @param[in] n_str_type The number of entries in the @a str_type_info_idx array. + * + * @return A bit mask of @ref MBG_COM_CFG_STATUS_MASKS flags indicating which type of parameter + * may not be fully supported. Should be 0 if everything is OK. + * + * @see ::is_valid_port_info + * @see @ref MBG_COM_CFG_STATUS_MASKS + */ + uint32_t check_valid_port_info( const PORT_INFO *p_pi, const STR_TYPE_INFO_IDX str_type_info_idx[], int n_str_type ) ; + + /** + * @brief Check if the content of a ::PORT_INFO structure is known and valid. + * + * @param[in] p_pi Address of a ::PORT_INFO structure to be checked. + * @param[in] str_type_info_idx An array of string type information. + * @param[in] n_str_type The number of entries in the @a str_type_info_idx array. + * + * @return @a true if the ::PORT_INFO structure contains valid data, + * else @a false. + * + * @see ::check_valid_port_info + */ + bool is_valid_port_info( const PORT_INFO *p_pi, const STR_TYPE_INFO_IDX str_type_info_idx[], int n_str_type ) ; + + /** + * @brief Setup an array of ::PORT_INFO_IDX structures from a ::PORT_PARM. + * + * Some legacy GPS receivers that don't provide a ::RECEIVER_INFO structure + * also provide a ::PORT_PARM structure with the current serial port settings + * only. + * + * This function sets up an array of ::PORT_INFO_IDX structures with the + * associated settings, and fills up the remaining ::PORT_INFO fields with + * the well-known supported settings, so applications can simply deal with + * the current API structures. + * + * @param[out] pii Array with @a p_ri->n_com_ports ::PORT_INFO_IDX elements to be filled up. + * @param[in] p_pp Pointer to a ::PORT_PARM structure providing the current COM port settings. + * @param[in] p_ri Pointer to a ::RECEIVER_INFO structure providing the number of supported COM ports. + * + * @return One of the @ref MBG_RETURN_CODES, but actually always ::MBG_SUCCESS. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see setup_default_str_type_info_idx + */ + int setup_port_info_from_port_parm( PORT_INFO_IDX pii[], const PORT_PARM *p_pp, const RECEIVER_INFO *p_ri ) ; + + /** + * @brief Setup an array of ::STR_TYPE_INFO_IDX for well-known string types. + * + * Some legacy GPS receivers that don't provide a ::RECEIVER_INFO structure + * also don't support the ::STR_TYPE_INFO structure to indicate which serial + * string formats are supported. + * + * This function sets up an array of ::STR_TYPE_INFO_IDX structures with the + * well-known supported string types, so applications can simply deal with + * the current API structures. + * + * @param[out] stii Array with at least @a p_ri->n_str_type ::STR_TYPE_INFO_IDX elements to be filled up. + * @param[in] p_ri Pointer to a ::RECEIVER_INFO structure providing the number of supported COM ports. + * + * @return One of the @ref MBG_RETURN_CODES, but actually always ::MBG_SUCCESS. + * + * @ingroup cfg_hlp_com_parm_cnv_fncs + * @see ::setup_port_info_from_port_parm + */ + int setup_default_str_type_info_idx( STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) ; + + /** + * @brief Determine how many GNSS systems are marked to be supported. + * + * This function counts the number of bits that are set to indicate + * that specific GNSS types (GPS, GLONASS, Galileo, ...) are supported + * by the device, and sets up the ::ALL_GNSS_INFO::n_gnss_supp field + * accordingly. + * + * @param[in,out] p_agi Address of an ::ALL_GNSS_INFO structure to be updated. + * + * @return ::MBG_SUCCESS on success, or ::MBG_ERR_N_GNSS_EXCEEDS_SUPP if the + * number of bits that are set exceeds the number of known GNSS types. + */ + int chk_set_n_gnss_supp( ALL_GNSS_INFO *p_agi ) ; + + /** + * @brief Setup GNSS sat info from the legacy GPS ::STAT_INFO. + * + * This simplyifies further evaluation since e.g. a common + * display routine can be used. + * + * @param[in,out] p_agi Address of an ::ALL_GNSS_INFO structure to be updated. + */ + void setup_gps_only_gnss_sat_info_idx_from_stat_info( ALL_GNSS_INFO *p_agi ) ; + + /** + * @brief Setup GNSS mode info from the legacy GPS ::STAT_INFO. + * + * This simplyifies further evaluation since e.g. a common + * display routine can be used. + * + * @param[in,out] p_agi Address of an ::ALL_GNSS_INFO structure to be updated. + */ + int setup_gps_only_gnss_mode_info_from_stat_info( ALL_GNSS_INFO *p_agi ) ; + + void chk_free_dev_hw_id( DEVICE_INFO *p ) ; + int alloc_dev_hw_id( DEVICE_INFO *p, size_t len ) ; + const char *get_fw_id_from_hw_id( const char *hw_id ) ; + const char *get_hw_id_from_fw_id( const char *fw_id ) ; + /** + * @brief Return the currently used ::MBG_IO_PORT_TYPE_INFO for the appropriate ::MBG_IO_PORT. + * + * @param[in] port Pointer to the ::MBG_IO_PORT to search for port_type + * @param[in] port_type Enum value of ::MBG_IO_PORT_TYPES to search for in @a port (::MBG_IO_PORT) + * + * @return Pointer to the ::MBG_IO_PORT_TYPE_INFO_IDX found, or NULL. + */ + MBG_IO_PORT_TYPE_INFO *get_io_port_type_info( const MBG_IO_PORT *port, uint16_t port_type ) ; + + /** + * @brief Initialize a ::MBG_TLV_ANNOUNCE structure. + * + * @param[out] tlv Pointer to a ::MBG_TLV_ANNOUNCE structure. + * @param[in] uid Unique sender ID used as identifier with all + * subsequent messages related to this transaction. + * @param[in] tlv_feat_type One of the ::MBG_TLV_FEAT_TYPES. + * @param[in] total_bytes Total number of bytes of all upcoming TLVs. + */ + void mbg_tlv_announce_init( MBG_TLV_ANNOUNCE *tlv, MBG_TLV_UID uid, MBG_TLV_TYPE tlv_feat_type, uint32_t total_bytes ) ; + + /** + * @brief Initialize a ::MBG_TLV structure. + * + * @param[out] tlv Pointer to a valid ::MBG_TLV structure. + * @param[in] uid Unique sender ID used as identifier for each further + * TLV message related to this type. + * @param[in] tlv_type Type identifier, see ::MBG_TLV_TYPES. + * @param[in] total_bytes Total number of bytes belonging to this TLV transaction + * (which is very likely split into several TLVs) + */ + void mbg_tlv_init( MBG_TLV *tlv, MBG_TLV_UID uid, MBG_TLV_TYPE tlv_type, uint32_t total_bytes ) ; + + /** + * @brief Initialize ::MBG_TLV_RCV_STATE structure. + * + * @param[out] state Pointer to ::MBG_TLV_RCV_STATE structure to be initialized. + * @param[in] uid Unique sender ID used as identifier for each further + * TLV message related to this type. + * @param[in] total_bytes Total number of bytes belonging to this TLV transaction + * (which is very likely split into several TLVS) + */ + void mbg_tlv_rcv_state_init( MBG_TLV_RCV_STATE *state, MBG_TLV_UID uid, uint32_t total_bytes ) ; + + /** + * @brief Print some Meinberg OS revision information into a string buffer. + * + * @param[out] s The string buffer to be filled. + * @param[in] max_len Size of the output buffer for 0-terminated string. + * @param[in] prefix Pointer to an optional prefix string, or NULL. + * @param[in] suffix Pointer to an optional suff string, or NULL. + * @param[in] rev The revision code which will be split into major, minor, and patch version. + * + * @return Length of the string in the buffer. + * + * @see @ref group_ext_sys_info + */ + int mbg_snprint_revision( char *s, size_t max_len, const char *prefix, const char *suffix, uint32_t rev ) ; + + /** + * @brief Check if all ::RECEIVER_INFO capabilities reported by a device are supported by the current driver. + * + * @param[in] p Address of a ::RECEIVER_INFO structure to be checked. + * + * @return ::MBG_SUCCESS if everything is OK, one of the @ref MBG_ERROR_CODES, as appropriate. + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_receiver_info( const RECEIVER_INFO *p ) ; + + _NO_MBG_API_ATTR int _MBG_API chk_dev_xbp_supp_nodes( const ALL_XBP_INFO *info ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_net_cfg_supp_stage_2( const ALL_NET_CFG_INFO *info ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_ntp_supp_client( const ALL_NTP_CFG_INFO *info ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_ntp_supp_server( const ALL_NTP_CFG_INFO *info ) ; + /** + * @brief Check if the ::XMULTI_EXT_REF_INSTANCES structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_supp_ext_instances( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if the ::XMULTI_EXT_REF_INSTANCES structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_not_configurable( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if the ::XMRIF_BIT_NO_STATUS bit is set. + * + * If this feature bit is set, ***no*** status, stats, etc., are provided. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS if the bit is set, or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_no_status( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if the ::XMRIF_BIT_MRF_NONE_SUPP bit is set. + * + * If this feature bit is set, the MRS pseudo-type ::MULTI_REF_NONE is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS if the bit is set, or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_mrf_none( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if the ::XMR_EXT_SRC_INFO structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_src_info( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if the ::::XMR_EXT_SRC_INFO structure is supported. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return ::MBG_SUCCESS or ::MBG_ERR_NOT_SUPP_BY_DEV, + * as returned by ::chk_mrs_instances_flags. + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_holdover_status( const ALL_XMULTI_REF_INFO *info ) ; + + /** + * @brief Check if an XMR source provides ::XMR_STATS. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::chk_dev_supp_xmulti_ref_ext_src_info + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_stats( const ALL_XMULTI_REF_INFO *info, int type ) ; + + /** + * @brief Check if an XMR source provides ::XMR_METRICS. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::chk_dev_xmulti_ref_supp_ext_source_adv_metrics + * @see ::chk_dev_supp_xmulti_ref_ext_src_info + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_metrics( const ALL_XMULTI_REF_INFO *info, int type ) ; + + /** + * @brief Check if an XMR source supports advanced XMR QL metrics configuration + * + * If this feature is not available, ::XMR_METRICS can not be configured. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::XMR_QL_LIMITS + * @see ::chk_dev_xmulti_ref_supp_ext_source_metrics + * @see ::chk_dev_supp_xmulti_ref_ext_src_info + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_adv_metrics( const ALL_XMULTI_REF_INFO *info, int type ) ; + + /** + * @brief Check if an XMR source XMR source supports coasting mode. + * + * If this feature is not available, ::XMR_METRICS can not be configured. + * + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * @param[in] type One of the ::MULTI_REF_TYPES, except ::MULTI_REF_NONE which is -1. + * + * @see ::XMR_QL_LIMITS + * @see ::chk_dev_supp_xmulti_ref_ext_src_info + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_xmulti_ref_supp_ext_source_coasting( const ALL_XMULTI_REF_INFO *info, int type ) ; + + _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_has_fdm( const ALL_IMS_INFO *info ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_volt_out_enabled( const ALL_IMS_STATE *ims_state, unsigned idx ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_volt_out_overload( const ALL_IMS_STATE *ims_state, unsigned idx ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_ims_is_pll_locked( const ALL_IMS_STATE *ims_state, unsigned idx ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_supp_ass_idx( const ALL_GPIO_INFO *gpio_info, unsigned idx ) ; + _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_dep_on_ass_idx( const ALL_GPIO_INFO *gpio_info, unsigned idx ) ; + /** + * @brief Check whether GPIO provides a status. + * + * @param[out] info Pointer to a ::ALL_GPIO_INFO structure to be filled up ::FIXME + * @param[in] info Address of an ::ALL_XMULTI_REF_INFO structure to be checked. + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio + * @see ::free_all_gpio_info + */ + _NO_MBG_API_ATTR int _MBG_API chk_dev_gpio_has_status( const ALL_GPIO_INFO *info ) ; + + /** + * @brief Free an ::ALL_XBP_INFO structure + * + * @param[in] p Pointer to the ::ALL_XBP_INFO structure to be freed + * + * @see ::mbgextio_get_all_xbp_info + */ + void free_all_xbp_info( ALL_XBP_INFO *p ) ; + + /** + * @brief Free an ::ALL_NET_CFG_INFO structure + * + * @param[in] p Pointer to the ::ALL_NET_CFG_INFO structure to be freed + * + * @see ::mbgextio_get_all_net_cfg_info + */ + void free_all_net_cfg_info( ALL_NET_CFG_INFO *p ) ; + + /** + * @brief Free an ::ALL_NET_STATUS_INFO structure + * + * @param[in] p Pointer to the ::ALL_NET_STATUS_INFO structure to be freed + * + * @see ::mbgextio_get_all_net_status_info + */ + void free_all_net_status_info( ALL_NET_STATUS_INFO *p ) ; + + /** + * @brief Free an ::ALL_SNMP_INFO structure + * + * @param[in] p Pointer to the ::ALL_SNMP_INFO structure to be freed + */ + void free_all_snmp_info ( ALL_SNMP_INFO *p ) ; + + /** + * @brief Free an ::ALL_SYSLOG_INFO structure + * + * @param[in] p Pointer to the ::ALL_SYSLOG_INFO structure to be freed + */ + void free_all_syslog_info ( ALL_SYSLOG_INFO *p ) ; + + /** + * @brief Free an ::ALL_MONITORING_INFO structure + * + * @param[in] p Pointer to the ::ALL_MONITORING_INFO structure to be freed + */ + void free_all_monitoring_info ( ALL_MONITORING_INFO *p ) ; + + /** + * @brief Free an ::ALL_EVENTS structure + * + * @param[in] p Pointer to the ::ALL_EVENTS structure to be freed + */ + void free_all_events( ALL_EVENTS *p ) ; + + /** + * @brief Free an ::ALL_XMULTI_REF_INFO structure + * + * @param[in] p Pointer to the ::ALL_XMULTI_REF_INFO structure to be freed + * + * @see ::mbgextio_get_all_xmulti_ref_info + * @see ::mbg_get_all_xmulti_ref_info + */ + void free_all_xmulti_ref_info( ALL_XMULTI_REF_INFO *p ) ; + + /** + * @brief Free an ::ALL_XMULTI_REF_STATUS structure + * + * @param[in] p Pointer to the ::ALL_XMULTI_REF_STATUS structure to be freed + * + * @see ::mbgextio_get_all_xmulti_ref_status + * @see ::mbg_get_all_xmulti_ref_status + */ + void free_all_xmulti_ref_status( ALL_XMULTI_REF_STATUS *p ) ; + + /** + * @brief Free an ::ALL_PTP_V1_COMMON_DATASETS structure allocated by ::mbgextio_get_all_ptp_v1_common_datasets + * + * @param[in] p Pointer to the ::ALL_PTP_V1_COMMON_DATASETS structure to be freed + * + * @see ::mbgextio_get_all_ptp_v1_common_datasets + */ + void free_all_ptp_v1_common_datasets( ALL_PTP_V1_COMMON_DATASETS *p ) ; + + /** + * @brief Free an ::ALL_PTP_V2_COMMON_DATASETS structure allocated by ::mbgextio_get_all_ptp_v2_common_datasets + * + * @param[in] p Pointer to the ::ALL_PTP_V2_COMMON_DATASETS structure to be freed + * + * @see ::mbgextio_get_all_ptp_v2_common_datasets + */ + void free_all_ptp_v2_common_datasets( ALL_PTP_V2_COMMON_DATASETS *p ) ; + + /** + * @brief Free an ::ALL_NTP_CFG_INFO structure + * + * @param[in] p Pointer to the ::ALL_NTP_CFG_INFO structure to be freed + * + * @see ::mbgextio_get_all_ntp_cfg_info + */ + void free_all_ntp_cfg_info( ALL_NTP_CFG_INFO *p ) ; + + /** + * @brief Free an ::ALL_NTP_STATUS structure + * + * @param[in] p Pointer to the ::ALL_NTP_STATUS structure to be freed + * + * @see ::mbgextio_get_all_ntp_status + */ + void free_all_ntp_status( ALL_NTP_STATUS *p ) ; + + /** + * @brief Free an ::ALL_PTP_NG_INFO structure + * + * @param[in] p Pointer to the ::ALL_PTP_NG_INFO structure to be freed + * + * @see ::mbgextio_get_all_ptp_ng_info + */ + void free_all_ptp_ng_info( ALL_PTP_NG_INFO *p ) ; + + /** + * @brief Free a list of ::MBG_SYS_REF_SRC structures + * + * @param[in] p Pointer to the ::MBG_SYS_REF_SRC list to be freed + * @param[in] free_source Address of a function to be called to free resources. + * + * @see ::mbgextio_get_all_sys_ref_info + * @see ::free_all_sys_ref_info + */ + void free_all_sys_ref_srcs( struct mbg_klist_head *p, void (*free_source)( MBG_SYS_REF_SRC * ) ) ; + + /** + * @brief Free an ::ALL_SYS_REF_INFO structure + * + * @param[in] p Pointer to the ::ALL_SYS_REF_INFO structure to be freed + * + * @see ::mbgextio_get_all_sys_ref_info + * @see ::free_all_sys_ref_srcs + */ + void free_all_sys_ref_info( ALL_SYS_REF_INFO *p ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_ims_info + * + * @param[in] p Pointer to the ::ALL_IMS_INFO structure to be freed + * + * @see ::mbgextio_dev_has_ims + * @see ::mbgextio_get_all_ims_info + * @see ::mbgextio_get_all_ims_state + */ + void free_all_ims_info( ALL_IMS_INFO *p ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_ims_state + * + * @param[in] p Pointer to the ::ALL_IMS_STATE structure to be freed + * + * @see ::mbgextio_dev_has_ims + * @see ::mbgextio_get_all_ims_info + * @see ::mbgextio_get_all_ims_state + */ + void free_all_ims_state( ALL_IMS_STATE *p ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_gpio_info + * + * @param[in] p Pointer to the ::ALL_GPIO_INFO structure to be freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_gpio + * @see ::mbgextio_get_all_gpio_info + */ + void free_all_gpio_info( ALL_GPIO_INFO *p ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_io_ports + * + * @param[in] p Pointer to the ::ALL_MBG_IO_PORTS structure to be freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_io_ports + * @see ::mbgextio_get_all_io_ports + * @see ::mbgextio_get_all_io_port_status + */ + void free_all_io_ports( ALL_MBG_IO_PORTS *p ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_gpio_state + * + * @param[in] p Pointer to the ::ALL_GPIO_STATE structure to be freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_gpio + * @see ::mbgextio_get_all_gpio_state + */ + void free_all_gpio_state( ALL_GPIO_STATE *p ) ; + + /** + * Allocates memory for a new ::UCAP_ENTRY structure + * + * @return The new allocated ::UCAP_ENTRY or NULL if the calloc call was not successful + */ + UCAP_ENTRY *calloc_ucap_entry( void ) ; + + /** + * @brief Free memory allocated by ::mbgextio_get_all_ucap_info + * + * @param[in] p Pointer to the ::ALL_UCAP_INFO structure to freed + * + * @return One of the @ref MBG_RETURN_CODES + * + * @see ::mbgextio_dev_has_ucap + * @see ::mbg_chk_dev_has_ucap + * @see ::mbgextio_get_all_ucap_info + * @see ::mbg_get_all_ucap_info + */ + void free_all_ucap_info( ALL_UCAP_INFO *p ) ; + + /** + * @brief Free an ::ALL_UCAP_NET_INFO structure + * + * @param[in] p Pointer to the ::ALL_UCAP_NET_INFO structure to be freed + * + * @see ::mbgextio_get_all_ucap_net_info + */ + void free_all_ucap_net_info( ALL_UCAP_NET_INFO *p ) ; + + /** + * @brief Free an ::ALL_USER_INFO structure + * + * @param[in] p Pointer to the ::ALL_USER_INFO structure to be freed + * + * @see ::mbgextio_get_all_user_info + */ + void free_all_user_info( ALL_USER_INFO *p ) ; + + /** + * @brief Free an ::ALL_SERVICE_INFO structure + * + * @param[in] p Pointer to the ::ALL_SERVICE_INFO structure to be freed + * + * @see ::mbgextio_get_all_user_info + */ + void free_all_svc_info( ALL_SERVICE_INFO *p ) ; + + /** + * @brief Free an ::ALL_FIRMWARE_INFO structure + * + * @param[in] p Pointer to the ::ALL_FIRMWARE_INFO structure to be freed + * + * @see ::mbgextio_get_all_firmware_info + */ + void free_all_firmware_info( ALL_FIRMWARE_INFO *p ) ; + + /** + * @brief Free an ::ALL_DATABASE_INFO structure + * + * @param[in] p Pointer to the ::ALL_DATABASE_INFO structure to be freed + * + * @see ::mbgextio_get_all_database_info + */ + void free_all_database_info( ALL_DATABASE_INFO *p ) ; + + /** + * @brief Set up a ::NTP_TSTAMP structure from a hex string with a time in seconds and binary fractions + * + * @param[in] s A string with a time in seconds since NTP epoch 1900-01-01, + * with binary fractions separated by decimal point, + * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility + * @param[out] p Address of a ::NTP_TSTAMP structure to be set up + * + * @see ::str_ntp_hex_to_nano_time_64 + */ + void str_ntp_hex_to_ntp_tstamp( const char *s, NTP_TSTAMP *p ) ; + + /** + * @brief Convert a ::NTP_TSTAMP structure to a ::NANO_TIME_64 structure + * + * @param[in] p_nts The ::NTP_TSTAMP structure to be converted + * @param[out] p_nt64 The ::NANO_TIME_64 structure to be filled up + */ + void ntp_tstamp_to_nanotime_64( const NTP_TSTAMP *p_nts, NANO_TIME_64 *p_nt64 ) ; + + /** + * @brief Set up a ::NANO_TIME_64 structure from a hex string with a time in seconds and binary fractions + * + * @param[in] s A string with a time in seconds since epoch 1900-01-01, + * with binary fractions separated by decimal point, + * e.g. 'dc763e43.73bd5a8f' as printed by the ntpq utility + * @param[out] p Address of a ::NANO_TIME_64 structure to be set up + * + * @see ::str_ntp_hex_to_ntp_tstamp + */ + void str_ntp_hex_to_nano_time_64( const char *s, NANO_TIME_64 *p ) ; + + /** + * @brief Convert PTP binary config to Oregano config file + * + * @param[in] ptp_info Complete PTP config binary structure + * @param[in] instc PTP instance to write config for + * @param[in] inst_num PTP instance number on its timestamper + * @param[in] intf_lnk Associated interface link settings to determine VLAN ID + * @param[in] ip_addr Associated interface link settings to determine VLAN ID + * @param[in] ascii_file_name Target file name for the oregano cfg file + * + */ + _NO_MBG_API_ATTR int _MBG_API mbg_cnv_ptp_cfg_to_oreg_cfg_file( const ALL_PTP_NG_INFO *ptp_info, const MBG_PTP_NG_INSTC *instc, unsigned inst_num, const MBG_NET_INTF_LINK_SETTINGS *intf_lnk, const MBG_IP_ADDR *ip_addr, const char *ascii_file_name ) ; + + /** + * @brief cnvrt_bytes_to_long + */ + uint64_t cnvrt_bytes_to_long( const uint8_t byte_array[], int num_bytes ) ; + + /** + * @brief cnvrt_long_to_bytes + */ + void cnvrt_long_to_bytes( uint8_t byte_array[], int num_bytes, uint64_t val ) ; + + size_t nw_str_mac_addr_to_str( MBG_MAC_ADDR *mac_addr, char *buf, size_t buflen ) ; + int nw_str_to_mac_addr( MBG_MAC_ADDR *mac_addr, const char *str ) ; + int nw_ip6_addr_bytes_to_str( const uint8_t *addr, uint8_t protocol, char *str, size_t buflen ) ; + int nw_str_to_ip6_addr_bytes( uint8_t *addr, const uint8_t protocol, char *str, size_t buflen ) ; + int mbg_os_version_to_str( const MBG_EXT_SYS_INFO *info, char *buf, size_t buflen, int long_version ) ; + int mbg_fw_can_set_osv(const MBG_FW_GLB_INFO *info) ; + +/* ----- function prototypes end ----- */ + +#endif // !defined( MBG_TGT_KERNEL ) + +#ifdef __cplusplus +} +#endif + + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _CFG_HLP_H */ diff --git a/c/mbglib/include/deviohlp.h b/c/mbglib/include/deviohlp.h deleted file mode 100644 index 79c9b4d..0000000 --- a/c/mbglib/include/deviohlp.h +++ /dev/null @@ -1,181 +0,0 @@ - -/************************************************************************** - * - * $Id: deviohlp.h 1.1.1.10 2012/07/18 11:00:46Z martin TEST $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for deviohlp.c. - * - * ----------------------------------------------------------------------- - * $Log: deviohlp.h $ - * Revision 1.1.1.10 2012/07/18 11:00:46Z martin - * Revision 1.1.1.9 2012/07/12 09:07:36Z martin - * Revision 1.1.1.8 2012/07/12 08:38:51Z martin - * Account for renamed structure. - * Revision 1.1.1.7 2012/07/10 09:53:57 martin - * Revision 1.1.1.6 2012/04/11 15:45:10Z martin - * Updated doxygen comments. - * Revision 1.1.1.5 2011/09/21 16:00:22 martin - * Revision 1.1.1.4 2011/09/21 14:44:50 martin - * Updated function prototypes. - * Revision 1.1.1.3 2011/09/20 15:36:03 marvin - * new functions: - * mbg_get_serial_settings - * mbg_set_serial_settings - * include mbgextio.h - * Revision 1.1.1.2 2011/08/05 10:30:28 martin - * Revision 1.1.1.1 2011/08/05 09:55:58 martin - * Revision 1.1 2011/08/03 15:36:44Z martin - * Initial revision with functions moved here from mbgdevio. - * - **************************************************************************/ - -#ifndef _DEVIOHLP_H -#define _DEVIOHLP_H - - -/* Other headers to be included */ - -#include <mbgdevio.h> -#include <cfg_hlp.h> - - -#ifdef _DEVIOHLP - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#ifdef __cplusplus -extern "C" { -#endif - - -typedef struct -{ - PTP_CFG_INFO ptp_cfg_info; - PTP_UC_MASTER_CFG_LIMITS ptp_uc_master_cfg_limits; - ALL_PTP_UC_MASTER_INFO_IDX all_ptp_uc_master_info_idx; - -} ALL_PTP_CFG_INFO; - - - -/* function prototypes: */ - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - /** - Read all serial port settings and supported configuration parameters. - - The functions mbg_get_device_info() and mbg_setup_receiver_info() - must have been called before, and the returned ::PCPS_DEV and - ::RECEIVER_INFO structures must be passed to this function. - - The complementary function mbg_save_serial_settings() should be used - to write the modified serial port configuration back to the board. - - @param dh Valid handle to a Meinberg device. - @param *pdev Pointer to a ::PCPS_DEV structure. - @param *pcfg Pointer to a ::RECEIVER_PORT_CFG structure to be filled up. - @param *p_ri Pointer to a ::RECEIVER_INFO structure. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_device_info() - @see mbg_setup_receiver_info() - @see mbg_save_serial_settings() -*/ - int mbg_get_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, RECEIVER_PORT_CFG *pcfg, const RECEIVER_INFO *p_ri ) ; - - /** - Write the configuration settings for a single serial port to the board. - - Modifications to the serial port configuration should be made only - after mbg_get_serial_settings() had been called to read all serial port - settings and supported configuration parameters. - This function has finally to be called once for every serial port - the configuration of which has been modified. - - As also required by mbg_get_serial_settings(), the functions - mbg_get_device_info() and mbg_setup_receiver_info() must have been - called before, and the returned ::PCPS_DEV and ::RECEIVER_INFO structures - must be passed to this function. - - @param dh Valid handle to a Meinberg device - @param *pdev Pointer to a ::PCPS_DEV structure - @param *pcfg Pointer to a ::RECEIVER_PORT_CFG structure - @param port_num Index of the ::serial port to be saved - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_serial_settings() - @see mbg_get_device_info() - @see mbg_setup_receiver_info() -*/ - int mbg_save_serial_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, RECEIVER_PORT_CFG *pcfg, int port_num ) ; - - /** - Read all PTP settings and supported configuration parameters. - - The complementary function mbg_save_all_ptp_cfg_info() should - be used to write the modified configuration back to the device. - - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::ALL_PTP_CFG_INFO structure. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_save_all_ptp_cfg_info() - @see mbg_get_ptp_cfg_info() - @see mbg_get_ptp_uc_master_cfg_limits() - @see mbg_get_all_ptp_uc_master_info() - @see mbg_dev_has_ptp() - @see mbg_dev_has_ptp_unicast() -*/ - int mbg_get_all_ptp_cfg_info( MBG_DEV_HANDLE dh, ALL_PTP_CFG_INFO *p ) ; - - /** - Write all PTP settings and supported configuration parameters - to a device. - - The complementary function mbg_get_all_ptp_cfg_info() should - have been used to read the original PTP settings and supported - configuration parameters. - - @param dh Valid handle to a Meinberg device. - @param *p Pointer to a ::ALL_PTP_CFG_INFO structure. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbg_get_all_ptp_cfg_info() - @see mbg_set_ptp_cfg_settings() - @see mbg_set_ptp_uc_master_settings_idx() - @see mbg_dev_has_ptp() - @see mbg_dev_has_ptp_unicast() -*/ - int mbg_save_all_ptp_cfg_info( MBG_DEV_HANDLE dh, const ALL_PTP_CFG_INFO *p ) ; - - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - - -/* End of header body */ - -#undef _ext -#undef _DO_INIT - -#endif /* _DEVIOHLP_H */ diff --git a/c/mbglib/include/eventlog.h b/c/mbglib/include/eventlog.h deleted file mode 100644 index 576d3f8..0000000 --- a/c/mbglib/include/eventlog.h +++ /dev/null @@ -1,89 +0,0 @@ - -/************************************************************************** - * - * $Id: eventlog.h 1.4 2014/03/05 10:38:46Z martin TRASH $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for eventlog.c. - * - * ----------------------------------------------------------------------- - * $Log: eventlog.h $ - * Revision 1.4 2014/03/05 10:38:46Z martin - * Windows.h is now included in mbg_tgt.h. - * Revision 1.3 2007/09/26 14:56:03Z martin - * Updated function prototypes. - * Revision 1.2 2004/04/14 08:36:54Z martin - * Pack structures 1 byte aligned. - * Revision 1.1 2002/11/28 09:18:36Z Martin - * Initial revision - * - **************************************************************************/ - -#ifndef _EVENTLOG_H -#define _EVENTLOG_H - - -/* Other headers to be included */ - -#include <mbg_tgt.h> -#include <use_pack.h> - - -#ifdef _EVENTLOG - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if defined( _USE_PACK ) // set byte alignment - #pragma pack( 1 ) -#endif - - -extern const char *eventlog_name; // must be provided by the application - - -#if defined( DEBUG ) || defined ( _DEBUG ) - #define reportDebugEvent( _p1, _p2 ) \ - reportAnEvent( _p1, _p2 ) -#else - #define reportDebugEvent( _p1, _p2 ); -#endif - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - void reportAnEvent( DWORD dwIdEvent, const char *message ) ; - void reportAnEventEx( DWORD dwIdEvent, const char *insert1, const char* insert2, int err_code ) ; - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - - -#if defined( _USE_PACK ) // set default alignment - #pragma pack() -#endif - -/* End of header body */ - -#undef _ext -#undef _DO_INIT - -#endif /* _EVENTLOG_H */ diff --git a/c/mbglib/include/extiohlp.h b/c/mbglib/include/extiohlp.h deleted file mode 100644 index ee744bc..0000000 --- a/c/mbglib/include/extiohlp.h +++ /dev/null @@ -1,116 +0,0 @@ - -/************************************************************************** - * - * $Id: extiohlp.h 1.2.1.1 2012/03/13 16:27:20Z martin TRASH $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for extiohlp.c. - * - * ----------------------------------------------------------------------- - * $Log: extiohlp.h $ - * Revision 1.2.1.1 2012/03/13 16:27:20Z martin - * Revision 1.2 2012/03/09 08:35:51Z martin - * Updated function prototypes. - * Revision 1.1 2011/09/21 15:59:59 martin - * Initial revision. - * - **************************************************************************/ - -#ifndef _EXTIOHLP_H -#define _EXTIOHLP_H - - -/* Other headers to be included */ - -#include <mbgextio.h> - -#include <cfg_hlp.h> - - -#ifdef _EXTIOHLP - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#ifdef __cplusplus -extern "C" { -#endif - - - - - -/* function prototypes: */ - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - /** - Read all serial port settings and supported configuration parameters. - from a non bus level device - - The function mbgextio_get_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO must be passed to this function. - - The complementary function mbgextio_save_serial_settings() should - be used to write the modified configuration back to the device. - - @param dh Valid handle to a Meinberg device. - @param *pcfg Pointer to a ::RECEIVER_PORT_CFG structure to be filled up. - @param *p_ri Pointer to a ::RECEIVER_INFO structure. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbgextio_save_serial_settings() - @see mbgextio_get_receiver_info() -*/ - int mbgextio_get_serial_settings( MBG_MSG_CTL *pmctl, RECEIVER_PORT_CFG *pcfg, const RECEIVER_INFO *p_ri ) ; - - /** - Write the configuration settings for a single serial port via serial connection to the board. - - Modifications to the serial port configuration should be made only - after mbgextio_get_serial_settings() had been called to read all serial port - settings and supported configuration parameters. - This function has finally to be called once for every serial port - the configuration of which has been modified. - - As also required by mbgextio_get_serial_settings(), the function - mbgextio_get_receiver_info() must have been - called before, and the returned ::RECEIVER_INFO structure - must be passed to this function. - - @param dh Valid handle to a Meinberg device via serial connection - @param *pcfg Pointer to a ::RECEIVER_PORT_CFG structure - @param port_idx Index of the ::serial port to be saved - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbgextio_get_serial_settings() - @see mbgextio_get_receiver_info() -*/ - int mbgextio_save_serial_settings( MBG_MSG_CTL *dh, const RECEIVER_PORT_CFG *pcfg, int port_idx ) ; - - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - - -/* End of header body */ - -#undef _ext -#undef _DO_INIT - -#endif /* _EXTIOHLP_H */ diff --git a/c/mbglib/include/gpsdefs.h b/c/mbglib/include/gpsdefs.h index df30fe5..71d9043 100644 --- a/c/mbglib/include/gpsdefs.h +++ b/c/mbglib/include/gpsdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsdefs.h 1.120.1.24 2014/07/14 15:42:45Z martin TRASH martin $ + * $Id: gpsdefs.h 1.127 2019/09/27 13:10:17Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -13,37 +13,186 @@ * * ----------------------------------------------------------------------- * $Log: gpsdefs.h $ - * Revision 1.120.1.24 2014/07/14 15:42:45Z martin - * Revision 1.120.1.23 2014/07/09 15:08:10 martin - * Revision 1.120.1.22 2014/07/09 14:14:34 martin - * Revision 1.120.1.21 2014/07/09 09:25:14 martin - * Revision 1.120.1.20 2014/07/08 15:26:28Z martin - * Doxygen stuff. - * Revision 1.120.1.19 2014/07/08 10:45:14 martin - * Revision 1.120.1.18 2014/07/08 10:41:47 martin - * Revision 1.120.1.17 2014/07/08 10:33:20 martin - * Doxygen fixes. - * Revision 1.120.1.16 2014/07/08 09:46:20Z martin - * Doxygen fixes. - * Revision 1.120.1.15 2014/07/08 09:35:55 martin - * Removed obsolete/unused XMR flag. - * Revision 1.120.1.14 2014/07/08 08:45:20 martin - * Revision 1.120.1.13 2014/07/08 08:18:41 martin - * Doxygen stuff. - * Revision 1.120.1.12 2014/07/08 07:24:08 martin - * Revision 1.120.1.10 2014/07/07 11:29:21 martin - * Revision 1.120.1.9 2014/07/07 11:05:01 martin - * Revision 1.120.1.8 2014/07/07 08:34:55 martin - * Revision 1.120.1.7 2014/07/04 12:08:17 martin - * Revision 1.120.1.6 2014/07/04 08:00:02 martin - * Revision 1.120.1.5 2014/07/02 15:34:41 martin - * Modified holdover status structure - * Revision 1.120.1.4 2014/06/30 15:43:29 martin - * Revision 1.120.1.3 2014/06/26 13:38:06 martin - * Modified/extended MBG_GPIO_STATUS. - * Revision 1.120.1.2 2014/06/23 09:11:49 martin - * Revision 1.120.1.1 2014/06/19 15:13:25 martin - * Support GPIO status. + * Revision 1.127 2019/09/27 13:10:17Z martin + * New model codes MSHPS100, BPE_STM, VSI180, + * GNM181, RSCRDU_TTL, RSC2000, FCU200, REL1000_RC. + * Replaced old model CSM100 by MSSB100. + * Replaced old model USYNCPWR by CPC200. + * New PTP configuration structures. + * New PTP SMPTE stuff. + * Some extension of NTP configuration. + * XMR_QL_INFO was added to XMR API. + * Port types SPST and SPDT and some other IO stuff was added. + * New XBP device state 'outdated'. + * New MBG_EXT_SYS_STATUS stuff. + * New MBG_EVENTS stuff. + * New FCU stuff. + * New sysinfo definitions. + * New bit mask GNSS_SV_STAT_DUAL_FREQ_MSK. + * Updated some SyncE definitions. + * New string table initializers. + * New types GPS_WNUM, GPS_WSEC, and GPS_TICK. + * New types MBG_MSG_IDX and MBG_MSG_IDX_32. + * Struct names were added by thomas-b to support forward declarations. + * Added an enumeration MBG_DEV_CPU_TYPES and as well as an + * initializer MBG_DEV_CPU_TYPE_TABLE_INIT for a table indicating + * which CPU type is used on which hardware device. + * Renamed type TM_STATUS_EXT to TM_GPS_STATUS_EXT, which is + * more similar to the name TM_GPS_STATUS, but provided a #define + * to avoid build problems with existing code. + * Moved some structures here that were previously private. + * Moved definitions of ANN_LIMIT and ANN_LIMIT_DCF here. + * Lots of doxygen updates. + * Revision 1.126 2018/07/05 10:18:34 martin + * New models GPS_MODEL_PIO180, GPS_MODEL_FCM180, GPS_MODEL_TCR180USB, + * GPS_MODEL_SSP100, GPS_MODEL_GNS165, GPS_MODEL_RSC180RDMP, + * GPS_MODEL_GPS16X, GPS_MODEL_MSHPS100. + * New builtin features .._MODEL_HAS_UP_CONV, .._MODEL_HAS_MBG_OS. + * BUILTIN_FEAT_DCF_PZF_2 includes GPS_MODEL_IS_DCF_AM. + * Builtin features of some models were updated. + * Removed obsolete MBG_XFEATURE_USB_LOCK. + * New extended features MBG_XFEATURE_TAINTED_CFG, MBG_XFEATURE_PUSH_MSGS, + * MBG_XFEATURE_USER_AUTH, MBG_XFEATURE_USER_MNGMNT, MBG_XFEATURE_SERVICE, + * MBG_XFEATURE_UP_CONV, MBG_XFEATURE_FW_MNGMNT, MBG_XFEATURE_DAC_CTRL_PCI, + * MBG_XFEATURE_DATABASE, MBG_XFEATURE_GNSS_MODE. + * New string mode STR_CR_ON_SEC. + * Renamed legacy string modes to LGCY_STR_ON_REQ, etc. and provided + * compatibility definitions for old firmware builds. + * New XMR_SETTINGS_FLAG_BITS: XMRSF_BIT_IS_TRUSTED_SRC, + * XMRSF_BIT_USE_TRUSTED_SRC, XMRSF_BIT_IS_TIME_OF_DAY_SRC, + * XMRSF_BIT_IS_PHASE_SRC. + * New XMR_REF_STATUS_BITS: XMRS_BIT_TRS_LIMIT_VIOLATED. + * New XMR_INST_FLAGS: XMRIF_BIT_GNSS_BIAS_SUPP. + * New XMR_EXT_SRC_FEAT_FLAG_BITS: XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING. + * Some MBG_EVT_IDS numbers were added. + * Some MBG_IMS_SENSORS were added. + * New MBG_NET_GLB_CFG_INFO_FLAGS: MBG_NET_GLB_SUPP_ADD_CONF, + * MBG_NET_GLB_SUPP_EXT_ROUTING. + * New MBG_NET_INTF_ADDR_BITS: MBG_NET_INTF_ADDR_BIT_AUTOCONF. + * Former PTP_CFG_SETTINGS::reserved field was split into + * PTP_CFG_SETTINGS::delay_asymmetry and PTP_CFG_SETTINGS::flags_ex. + * Former PTP_CFG_INFO::reserved_2 field was renmamed to + * PTP_CFG_INFO::supp_flags_ex. + * New PTP_CFG_FLAGS: PTP_CFG_ATOI, PTP_CFG_HAS_SMPTE_TLV_STATE, + * PTP_CFG_NTP_SW_SERVER, PTP_CFG_HAS_EXT_SUPP_FLAGS. + * New extended flags bits PTP_CFG_FLAGS_EX used with PTP configuration. + * New PTP profile ID PTP_OPT_EXT_C37238_2017. + * Former PTP_POWER_PROFILE_CFG::reserved_2 renamed to + * PTP_POWER_PROFILE_CFG::grandmaster_id_2017. + * New NTP_FLAGS: NTP_ADD_CONF and related definitions. + * NTP refclock configuration and statistics stuff was added. + * Former NTP_SYS_STATE::cfg_counter was renamed to + * NTP_SYS_STATE::service_state. + * IMS slot types were added. + * XBP_NODE_INFO structure was modified. + * New MBG_TLV_FEAT_TYPES: MBG_TLV_FEAT_TYPE_TIMEMON_FULL_STATUS. + * Some new MBG_EXT_SYS_INFO_BITS. + * OS type support was added. + * Extended management transactions support. + * Lots of new I/O port stuff. + * Some new definitions for SNMP support. + * New definitions for event logging. + * New tainted cfg stuff. + * Support for user and permission management. + * Support for services control. + * Support for firmware updates. + * Support for database management. + * Revision 1.125 2017/07/05 18:18:27 martin + * New models GPS_MODEL_CTC100, GPS_MODEL_TCR180, + * GPS_MODEL_LUE180, GPS_MODEL_CPC_01, GPS_MODEL_TSU_01, + * GPS_MODEL_CMC_01, GPS_MODEL_SCU_01, GPS_MODEL_FCU_01, + * GPS_MODEL_CSM100, GPS_MODEL_LNE180SFP, GPS_MODEL_GTS180, + * GPS_MODEL_GPS180CSM, GPS_MODEL_GRC181, GPS_MODEL_N2X180, + * GPS_MODEL_GNS181PEX, GPS_MODEL_MDU180, GPS_MODEL_MDU312, + * GPS_MODEL_GPS165, GPS_MODEL_GNS181_UC, GPS_MODEL_PSX_4GE, + * GPS_MODEL_RSC180RDU, GPS_MODEL_USYNCPWR, GPS_MODEL_FDM180M, + * GPS_MODEL_LSG180, GPS_MODEL_GPS190, GPS_MODEL_GNS181 and + * associated definitions. + * New GPS_BUILTIN_FEATURE_BITS and associated definitions. + * New macros _setup_default_receiver_info_dcf() and + * _setup_default_receiver_info_gps() as well as associated + * definitions which can be used to set up a RECEIVER_INFO + * structure for legacy devices which don't provide it. + * New Receiver_INO feature bit GPS_FEAT_XFEATURE which + * indicates that a new, extended feature set is supported. + * Defined a new st of extended features (MBG_XFEATURE_BITS) + * and associated definitions. + * Moved definitions for NANO_TIME and NANO_TIME_64 to words.h. + * New IRIG TX codes ICODE_TX_A006_A136, ICODE_TX_A007_A137, + * and associated definitions. + * Renamed ICODE_RX_G142_G146 to ICODE_RX_G142, and + * ICODE_RX_G002_G006 to ICODE_RX_G002. + * New IRIG RX codes ICODE_RX_A136_A137, ICODE_RX_A006_A007, + * ICODE_RX_G146, ICODE_RX_G006, and associated definitions. + * New union POUT_DATA union used for varying configuration + * data in POUT_SETTINGS, depending on the output mode. + * New POUT_MODES POUT_PTTI_PPS, POUT_HAVEQUICK, and + * associated definitions. + * Definitions to support a configurable pulse shift + * of some programmable output signals. + * New multiref source MULTI_REF_SYNCE and associated + * definitions. + * Added a number of swab..() macros that were still missing. + * XMR statistics, XMR_QL and some other XMR stuff by andre. + * New GPIO types including video modes, and associated stuff. + * Renamed some structure fields and added some definitions + * related to FDM. + * Added some SCU_STAT_MASKS. + * New GNSS_TYPE_QZSS, and modified MBG_GNSS_MODE_INFO. + * New flag MBG_GNSS_FLAG_HAS_SV_STATUS, structure + * GNSS_SV_STATUS and associated definitions. + * A bunch of new structures and definitions for network + * configuration. + * Many new structures and definitions for NTP configuration. + * New structures and associated definitions used to send + * user capture events over the network (ext_ucap). + * New PTP_ROLES and associated stuff. + * Changed one of PTP_STATE's reserved fields to tsu_secs. + * Changed PTP_ANN_RCPT_TIMEOUT_MAX from 255 to 8. + * New PTP_CFG_FLAGS, PTP_OPT_EXTS flags, PTP_PRESETS_MASKS + * and associated definitions. + * Definitions for PTPv1 and v2 data sets, and PTP statistics. + * Preliminary definitions to support SMPTE and SDH. + * Definition for XBP addressing of devices. + * Definitions to support TLVs. + * Added LED and LNE API definitions. + * MBG_EXT_SYS_INFO_BITS and associated definitions for an + * extended sysinfo API. + * MBG_CLK_RES_INFO and associated stuff for clock resolution + * info. + * Definitions for configuration transaction handling. + * Definitions for a higher level I/O port API. + * Definitions for monitoring / notification. + * Definitions for USB locking. + * Preliminary licensing stuff. + * Defined macros in a safer way. + * Revision 1.124 2015/07/14 14:22:46 martin + * Doxygen fix. + * Revision 1.123 2015/07/06 13:00:10 martin + * Added definitions for VSG180, MSF180, WWVB180, and CPC180. + * Added definitions for PZF180. + * Definitions for SDI and MDU300 added by stephan. + * Definitions for HPS100 added by daniel. + * FDM180 and associated definitions added by paul. + * Started to support eXtended Binary Protocol (XBP). + * Merged daniel and gregoire's changes from the 1.120.2.x branch. + * Defines for IPv6 multicast scopes added by gregoire. + * XMR_EXT_SRC_INFO and associated XMR_SETTINGS_FLAG_MSKS flags + * defined by andre. + * Support XMULTI_REF_INFO::n_prio field again. + * Fixed _mbg_swab_gpio_cfg_limits() macro. + * Added MBG_NET_LINK_OPT_MASK_CAN_SYNCE to MBG_NET_LINK_OPT_MASKS. + * New PTP_ROLE_MASKS PTP_ROLE_NTP_SERVER and PTP_ROLE_NTP_CLIENT. + * Some PTP profile extensions added by daniel. + * Added missing defines for SPT. + * Added definitions for REL1000. + * Moved structure NANO_TIME_64 here. + * Revision 1.122 2014/07/29 08:57:44Z martin + * Updated doxygen comments. + * Revision 1.121 2014/07/17 09:41:50 martin + * Introduced XMR_HOLDOVER_STATUS, MBG_GPIO_STATUS, + * and associated definitions. + * Huge update and cleanup on doxygen comments. * Revision 1.120 2014/05/27 08:34:40 martin * Fixed braces in some _mbg_rcvr_is_..() macros. * Definitions used with extended network cfg, VST, and SHS. @@ -495,7 +644,6 @@ #ifndef _GPSDEFS_H #define _GPSDEFS_H - /* Other headers to be included */ #if defined( HAVE_CONFIG_H ) @@ -503,15 +651,16 @@ #include <config.h> #endif -// CLOCK_MEINBERG is defined in NTP's config.h if configured -// to support Meinberg clocks. +// CLOCK_MEINBERG is defined in the config.h file provided +// by the NTP project to support Meinberg clocks. #if !defined( CLOCK_MEINBERG ) - // avoid having to use these headers in non-Meinberg projects + // Avoid having to use these headers in non-Meinberg projects. #include <words.h> #include <use_pack.h> #endif + /* Start of header body */ #if defined( _USE_PACK ) @@ -527,8 +676,8 @@ /** * @brief GNSS satellite numbers * - * @todo: Check if MAX_SVNO_GLN is 94 instead of 95, and thus - * N_SVNO_GLN is 30 instead of 31, as reported by Wikipedia. + * @todo Check if ::MAX_SVNO_GLONASS is 94 instead of 95, and thus + * ::N_SVNO_GLONASS is 30 instead of 31, as reported by Wikipedia. */ enum GNSS_SVNOS { @@ -568,26 +717,37 @@ enum GNSS_SVNOS * model support the ::RECEIVER_INFO structure which contains * the actual value. */ - #define GPS_TICKS_PER_SEC DEFAULT_GPS_TICKS_PER_SEC ///< see ::DEFAULT_GPS_TICKS_PER_SEC + #define GPS_TICKS_PER_SEC DEFAULT_GPS_TICKS_PER_SEC ///< See ::DEFAULT_GPS_TICKS_PER_SEC #endif -typedef uint16_t SVNO; ///< the number of an SV (Space Vehicle, i.e. satellite) -typedef uint16_t HEALTH; ///< an SV's health code -typedef uint16_t CFG; ///< an SV's configuration code -typedef uint16_t IOD; ///< Issue-Of-Data code +typedef uint16_t SVNO; ///< The number of an SV (Space Vehicle, i.e. satellite). +typedef uint16_t HEALTH; ///< The 6 bit health code for an SV. +typedef uint16_t CFG; ///< The 4 bit configuration code for an SV. +typedef uint16_t IOD; ///< Issue-Of-Data code. + +typedef int16_t GPS_WNUM; ///< Type of a signed extended GPS week number. +typedef int16_t GPS_DNUM; ///< Type of a signed GPS day number as used with ::UTC. +typedef int32_t GPS_WSEC; ///< Type of a signed GPS second-of-week number. +typedef int32_t GPS_TICK; ///< Type of a signed tick-of-second number, see + ///< ::GPS_TICKS_PER_SEC and ::RECEIVER_INFO::ticks_per_sec. + + +typedef uint16_t MBG_MSG_IDX; ///< Standard type of an index number used with binary messages. +typedef uint32_t MBG_MSG_IDX_32; ///< Type of a 32 bit index number used with binary messages in some cases. /* the type of various checksums */ #ifndef _CSUM_DEFINED - typedef uint16_t CSUM; ///< checksum used by some structures stored in non-volatile memory + typedef uint16_t CSUM; ///< Checksum used by some structures stored in non-volatile memory. #define _CSUM_DEFINED - - #define _mbg_swab_csum( _p ) _mbg_swab16( _p ) #endif +#define _mbg_swab_csum( _p ) _mbg_swab16( _p ) + + /** * @brief The type of a GPS command code @@ -605,19 +765,22 @@ typedef uint16_t GPS_CMD; * * Contains a software revision code, plus an optional * identifier for a customized version. + * + * @see @ref group_ext_sys_info */ typedef struct { uint16_t code; ///< Version number, e.g. 0x0120 means v1.20 - char name[GPS_ID_STR_SIZE]; ///< Optional string identifying a customized version + char name[GPS_ID_STR_SIZE]; ///< Optional string identifying a customized firmware version, should be empty in standard versions uint8_t reserved; ///< Reserved field to yield even structure size } SW_REV; #define _mbg_swab_sw_rev( _p ) \ +do \ { \ _mbg_swab16( &(_p)->code ); \ -} +} while ( 0 ) @@ -642,6 +805,9 @@ typedef struct * the associated type of GPS data is not available. * * @see ::BVAR_FLAGS + * @see ::BVAR_FLAG_BITS + * @see ::BVAR_FLAG_NAMES + * @see ::BVAR_FLAG_NAMES_SHORT */ typedef uint16_t BVAR_STAT; @@ -661,15 +827,16 @@ typedef uint16_t BVAR_STAT; * @see ::BVAR_STAT * @see ::BVAR_FLAGS * @see ::BVAR_FLAG_NAMES + * @see ::BVAR_FLAG_NAMES_SHORT */ enum BVAR_FLAG_BITS { - BVAR_BIT_CFGH_INVALID, ///< Satellite configuration and health parameters incomplete - BVAR_BIT_ALM_NOT_COMPLETE, ///< Almanac parameters incomplete - BVAR_BIT_UTC_INVALID, ///< %UTC offset parameters incomplete - BVAR_BIT_IONO_INVALID, ///< Ionospheric correction parameters incomplete - BVAR_BIT_RCVR_POS_INVALID, ///< No valid receiver position available - N_BVAR_BIT ///< number of defined ::BVAR_STAT bits + BVAR_BIT_CFGH_INVALID, ///< Satellite configuration and health parameters incomplete. + BVAR_BIT_ALM_NOT_COMPLETE, ///< Almanac parameters incomplete. + BVAR_BIT_UTC_INVALID, ///< %UTC offset parameters incomplete. + BVAR_BIT_IONO_INVALID, ///< Ionospheric correction parameters incomplete. + BVAR_BIT_RCVR_POS_INVALID, ///< No valid receiver position available. + N_BVAR_BIT ///< number of defined ::BVAR_STAT bits. }; @@ -681,25 +848,27 @@ enum BVAR_FLAG_BITS * @see ::BVAR_STAT * @see ::BVAR_FLAG_BITS * @see ::BVAR_FLAG_NAMES + * @see ::BVAR_FLAG_NAMES_SHORT */ enum BVAR_FLAGS { - BVAR_CFGH_INVALID = ( 1UL << BVAR_BIT_CFGH_INVALID ), ///< see ::BVAR_BIT_CFGH_INVALID - BVAR_ALM_NOT_COMPLETE = ( 1UL << BVAR_BIT_ALM_NOT_COMPLETE ), ///< see ::BVAR_BIT_ALM_NOT_COMPLETE - BVAR_UTC_INVALID = ( 1UL << BVAR_BIT_UTC_INVALID ), ///< see ::BVAR_BIT_UTC_INVALID - BVAR_IONO_INVALID = ( 1UL << BVAR_BIT_IONO_INVALID ), ///< see ::BVAR_BIT_IONO_INVALID - BVAR_RCVR_POS_INVALID = ( 1UL << BVAR_BIT_RCVR_POS_INVALID ), ///< see ::BVAR_BIT_RCVR_POS_INVALID + BVAR_CFGH_INVALID = ( 1UL << BVAR_BIT_CFGH_INVALID ), ///< See ::BVAR_BIT_CFGH_INVALID + BVAR_ALM_NOT_COMPLETE = ( 1UL << BVAR_BIT_ALM_NOT_COMPLETE ), ///< See ::BVAR_BIT_ALM_NOT_COMPLETE + BVAR_UTC_INVALID = ( 1UL << BVAR_BIT_UTC_INVALID ), ///< See ::BVAR_BIT_UTC_INVALID + BVAR_IONO_INVALID = ( 1UL << BVAR_BIT_IONO_INVALID ), ///< See ::BVAR_BIT_IONO_INVALID + BVAR_RCVR_POS_INVALID = ( 1UL << BVAR_BIT_RCVR_POS_INVALID ), ///< See ::BVAR_BIT_RCVR_POS_INVALID }; #define BVAR_MASK ( ( 1UL << N_BVAR_BIT ) - 1 ) ///< Bit mask for all defined bits /** - * @brief String initializer for ::BVAR_STAT flag names + * @brief String initializer for long ::BVAR_STAT flag names. * - * @see ::BVAR_STAT + * @see ::BVAR_FLAG_NAMES_SHORT * @see ::BVAR_FLAG_BITS * @see ::BVAR_FLAGS + * @see ::BVAR_STAT */ #define BVAR_FLAG_NAMES \ { \ @@ -710,6 +879,25 @@ enum BVAR_FLAGS "Receiver position" \ } + + +/** + * @brief String initializer for short ::BVAR_STAT flag names. + * + * @see ::BVAR_FLAG_NAMES + * @see ::BVAR_FLAG_BITS + * @see ::BVAR_FLAGS + * @see ::BVAR_STAT + */ +#define BVAR_FLAG_NAMES_SHORT \ +{ \ + "CFGH", \ + "Alm.", \ + "UTC", \ + "IONO", \ + "Rcvr. pos." \ +} + /** @} defgroup group_bvar_stat */ @@ -727,10 +915,11 @@ typedef struct } FIXED_FREQ_INFO; #define _mbg_swab_fixed_freq_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->khz_val ); \ _mbg_swab16( &(_p)->range ); \ -} +} while ( 0 ) /** @@ -745,7 +934,7 @@ typedef uint32_t RI_FEATURES; ///< see @ref GPS_FEATURE_MASKS * * @note This may not be supported by some very old devices. */ -typedef struct +typedef struct receiver_info_s { uint16_t model_code; ///< identifier for receiver model, see ::GPS_MODEL_CODES SW_REV sw_rev; ///< software revision and ID @@ -762,11 +951,12 @@ typedef struct uint8_t n_com_ports; ///< number of on-board serial ports uint8_t n_str_type; ///< max num of string types supported by any port uint8_t n_prg_out; ///< number of programmable pulse outputs - uint16_t flags; ///< additional information, see ::RECEIVER_INFO_FLAG_BITS + uint16_t flags; ///< additional information, see ::RECEIVER_INFO_FLAG_MASKS } RECEIVER_INFO; #define _mbg_swab_receiver_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->model_code ); \ _mbg_swab_sw_rev( &(_p)->sw_rev ); \ @@ -774,7 +964,7 @@ typedef struct _mbg_swab32( &(_p)->features ); \ _mbg_swab_fixed_freq_info( &(_p)->fixed_freq ); \ _mbg_swab16( &(_p)->flags ); \ -} +} while ( 0 ) /** @@ -841,11 +1031,68 @@ enum GPS_MODEL_CODES GPS_MODEL_LNE_GB, GPS_MODEL_PPG180, GPS_MODEL_SCG, + GPS_MODEL_MDU300, + GPS_MODEL_SDI, + GPS_MODEL_FDM180, + GPS_MODEL_SPT, + GPS_MODEL_PZF180, + GPS_MODEL_REL1000, + GPS_MODEL_HPS100, + GPS_MODEL_VSG180, + GPS_MODEL_MSF180, + GPS_MODEL_WWVB180, + GPS_MODEL_CPC180, + GPS_MODEL_CTC100, + GPS_MODEL_TCR180, + GPS_MODEL_LUE180, + GPS_MODEL_CPC_01, + GPS_MODEL_TSU_01, + GPS_MODEL_CMC_01, + GPS_MODEL_SCU_01, + GPS_MODEL_FCU_01, + GPS_MODEL_MSSB100, + GPS_MODEL_LNE180SFP, + GPS_MODEL_GTS180, + GPS_MODEL_GPS180CSM, + GPS_MODEL_GRC181, + GPS_MODEL_N2X180, + GPS_MODEL_GNS181PEX, + GPS_MODEL_MDU180, + GPS_MODEL_MDU312, + GPS_MODEL_GPS165, + GPS_MODEL_GNS181_UC, + GPS_MODEL_PSX_4GE, + GPS_MODEL_RSC180RDU, + GPS_MODEL_CPC200, // FIXME Try if this works. This entry was originally defined as GPS_MODEL_USYNCPWR + // in 1.124.1.303, which was already obsolete right from the beginning. + GPS_MODEL_FDM180M, + GPS_MODEL_LSG180, // Line Signal Generator + GPS_MODEL_GPS190, + GPS_MODEL_GNS181, + GPS_MODEL_PIO180, // Programmable I/O module + GPS_MODEL_FCM180, // Fake Clock Module + GPS_MODEL_TCR180USB, + GPS_MODEL_SSP100, // Secure Sync Processor (HPS with USB-Lock) + GPS_MODEL_GNS165, + GPS_MODEL_RSC180RDMP, + GPS_MODEL_GPS16X, // Some legacy GPS receiver + GPS_MODEL_MSHPS100, // microSync based on HPS100 hardware (but) as USB host + GPS_MODEL_BPE_STM, // BPE with STM M0 + GPS_MODEL_VSI180, + GPS_MODEL_GNM181, + GPS_MODEL_RSCRDU_TTL, // TTL version of ::GPS_MODEL_RSC180RDU + GPS_MODEL_RSC2000, // Variant of ::GPS_MODEL_RSC180 for LANTIME M2000 + GPS_MODEL_FCU200, // Fan (and power supply) Control Unit + GPS_MODEL_REL1000_RC, N_GPS_MODEL /* If new model codes are added then care must be taken * to update the associated string initializers GPS_MODEL_NAMES * and GPS_MODEL_NAME_TABLE accordingly, and to check whether * the classification macros also cover the new model names. + * + * CARE MUST BE TAKEN that the name string of bus level devices + * is limited to 9 characters. Longer strings will not fit into + * the name field of the PCPS_DEV_TYPE structure. */ }; @@ -862,62 +1109,119 @@ enum GPS_MODEL_CODES * * @anchor GPS_MODEL_NAMES @{ */ -#define GPS_MODEL_NAME_UNKNOWN "(unknown)" -#define GPS_MODEL_NAME_GPS166 "GPS166" -#define GPS_MODEL_NAME_GPS167 "GPS167" -#define GPS_MODEL_NAME_GPS167SV "GPS167SV" -#define GPS_MODEL_NAME_GPS167PC "GPS167PC" -#define GPS_MODEL_NAME_GPS167PCI "GPS167PCI" -#define GPS_MODEL_NAME_GPS163 "GPS163" -#define GPS_MODEL_NAME_GPS168PCI "GPS168PCI" -#define GPS_MODEL_NAME_GPS161 "GPS161" -#define GPS_MODEL_NAME_GPS169PCI "GPS169PCI" -#define GPS_MODEL_NAME_TCR167PCI "TCR167PCI" -#define GPS_MODEL_NAME_GPS164 "GPS164" -#define GPS_MODEL_NAME_GPS170PCI "GPS170PCI" -#define GPS_MODEL_NAME_PZF511 "PZF511" -#define GPS_MODEL_NAME_GPS170 "GPS170" -#define GPS_MODEL_NAME_TCR511 "TCR511" -#define GPS_MODEL_NAME_AM511 "AM511" -#define GPS_MODEL_NAME_MSF511 "MSF511" -#define GPS_MODEL_NAME_GRC170 "GRC170" -#define GPS_MODEL_NAME_GPS170PEX "GPS170PEX" -#define GPS_MODEL_NAME_GPS162 "GPS162" -#define GPS_MODEL_NAME_PTP270PEX "PTP270PEX" -#define GPS_MODEL_NAME_FRC511PEX "FRC511PEX" -#define GPS_MODEL_NAME_GEN170 "GEN170" -#define GPS_MODEL_NAME_TCR170PEX "TCR170PEX" -#define GPS_MODEL_NAME_WWVB511 "WWVB511" -#define GPS_MODEL_NAME_MGR170 "MGR170" -#define GPS_MODEL_NAME_JJY511 "JJY511" -#define GPS_MODEL_NAME_PZF600 "PZF600" -#define GPS_MODEL_NAME_TCR600 "TCR600" -#define GPS_MODEL_NAME_GPS180 "GPS180" -#define GPS_MODEL_NAME_GLN170 "GLN170" -#define GPS_MODEL_NAME_GPS180PEX "GPS180PEX" -#define GPS_MODEL_NAME_TCR180PEX "TCR180PEX" -#define GPS_MODEL_NAME_PZF180PEX "PZF180PEX" -#define GPS_MODEL_NAME_MGR180 "MGR180" -#define GPS_MODEL_NAME_MSF600 "MSF600" -#define GPS_MODEL_NAME_WWVB600 "WWVB600" -#define GPS_MODEL_NAME_JJY600 "JJY600" -#define GPS_MODEL_NAME_GPS180HS "GPS180HS" -#define GPS_MODEL_NAME_GPS180AMC "GPS180AMC" -#define GPS_MODEL_NAME_ESI180 "ESI180" -#define GPS_MODEL_NAME_CPE180 "CPE180" -#define GPS_MODEL_NAME_LNO180 "LNO180" -#define GPS_MODEL_NAME_GRC180 "GRC180" -#define GPS_MODEL_NAME_LIU "LIU" -#define GPS_MODEL_NAME_DCF600HS "DCF600HS" -#define GPS_MODEL_NAME_DCF600RS "DCF600RS" -#define GPS_MODEL_NAME_MRI "MRI" -#define GPS_MODEL_NAME_BPE "BPE" -#define GPS_MODEL_NAME_GLN180PEX "GLN180PEX" -#define GPS_MODEL_NAME_N2X "N2X" -#define GPS_MODEL_NAME_RSC180 "RSC180" -#define GPS_MODEL_NAME_LNE_GB "LNE_GB" -#define GPS_MODEL_NAME_PPG180 "PPG180" -#define GPS_MODEL_NAME_SCG "SCG" +#define GPS_MODEL_NAME_UNKNOWN "Unknown" +#define GPS_MODEL_NAME_GPS166 "GPS166" +#define GPS_MODEL_NAME_GPS167 "GPS167" +#define GPS_MODEL_NAME_GPS167SV "GPS167SV" +#define GPS_MODEL_NAME_GPS167PC "GPS167PC" +#define GPS_MODEL_NAME_GPS167PCI "GPS167PCI" +#define GPS_MODEL_NAME_GPS163 "GPS163" +#define GPS_MODEL_NAME_GPS168PCI "GPS168PCI" +#define GPS_MODEL_NAME_GPS161 "GPS161" +#define GPS_MODEL_NAME_GPS169PCI "GPS169PCI" +#define GPS_MODEL_NAME_TCR167PCI "TCR167PCI" +#define GPS_MODEL_NAME_GPS164 "GPS164" +#define GPS_MODEL_NAME_GPS170PCI "GPS170PCI" +#define GPS_MODEL_NAME_PZF511 "PZF511" +#define GPS_MODEL_NAME_GPS170 "GPS170" +#define GPS_MODEL_NAME_TCR511 "TCR511" +#define GPS_MODEL_NAME_AM511 "AM511" +#define GPS_MODEL_NAME_MSF511 "MSF511" +#define GPS_MODEL_NAME_GRC170 "GRC170" +#define GPS_MODEL_NAME_GPS170PEX "GPS170PEX" +#define GPS_MODEL_NAME_GPS162 "GPS162" +#define GPS_MODEL_NAME_PTP270PEX "PTP270PEX" +#define GPS_MODEL_NAME_FRC511PEX "FRC511PEX" +#define GPS_MODEL_NAME_GEN170 "GEN170" +#define GPS_MODEL_NAME_TCR170PEX "TCR170PEX" +#define GPS_MODEL_NAME_WWVB511 "WWVB511" +#define GPS_MODEL_NAME_MGR170 "MGR170" +#define GPS_MODEL_NAME_JJY511 "JJY511" +#define GPS_MODEL_NAME_PZF600 "PZF600" +#define GPS_MODEL_NAME_TCR600 "TCR600" +#define GPS_MODEL_NAME_GPS180 "GPS180" +#define GPS_MODEL_NAME_GLN170 "GLN170" +#define GPS_MODEL_NAME_GPS180PEX "GPS180PEX" +#define GPS_MODEL_NAME_TCR180PEX "TCR180PEX" +#define GPS_MODEL_NAME_PZF180PEX "PZF180PEX" +#define GPS_MODEL_NAME_MGR180 "MGR180" +#define GPS_MODEL_NAME_MSF600 "MSF600" +#define GPS_MODEL_NAME_WWVB600 "WWVB600" +#define GPS_MODEL_NAME_JJY600 "JJY600" +#define GPS_MODEL_NAME_GPS180HS "GPS180HS" +#define GPS_MODEL_NAME_GPS180AMC "GPS180AMC" +#define GPS_MODEL_NAME_ESI180 "ESI180" +#define GPS_MODEL_NAME_CPE180 "CPE180" +#define GPS_MODEL_NAME_LNO180 "LNO180" +#define GPS_MODEL_NAME_GRC180 "GRC180" +#define GPS_MODEL_NAME_LIU "LIU" +#define GPS_MODEL_NAME_DCF600HS "DCF600HS" +#define GPS_MODEL_NAME_DCF600RS "DCF600RS" +#define GPS_MODEL_NAME_MRI "MRI" +#define GPS_MODEL_NAME_BPE "BPE" +#define GPS_MODEL_NAME_GLN180PEX "GLN180PEX" +#define GPS_MODEL_NAME_N2X "N2X" +#define GPS_MODEL_NAME_RSC180 "RSC180" +#define GPS_MODEL_NAME_LNE_GB "LNE_GB" +#define GPS_MODEL_NAME_PPG180 "PPG180" +#define GPS_MODEL_NAME_SCG "SCG" +#define GPS_MODEL_NAME_MDU300 "MDU300" +#define GPS_MODEL_NAME_SDI "SDI" +#define GPS_MODEL_NAME_FDM180 "FDM180" +#define GPS_MODEL_NAME_SPT "SPT" +#define GPS_MODEL_NAME_PZF180 "PZF180" +#define GPS_MODEL_NAME_REL1000 "REL1000" +#define GPS_MODEL_NAME_HPS100 "HPS100" +#define GPS_MODEL_NAME_VSG180 "VSG180" +#define GPS_MODEL_NAME_MSF180 "MSF180" +#define GPS_MODEL_NAME_WWVB180 "WWVB180" +#define GPS_MODEL_NAME_CPC180 "CPC180" +#define GPS_MODEL_NAME_CTC100 "CTC100" +#define GPS_MODEL_NAME_TCR180 "TCR180" +#define GPS_MODEL_NAME_LUE180 "LUE180" +#define GPS_MODEL_NAME_CPC_01 "CPC_01" +#define GPS_MODEL_NAME_TSU_01 "TSU_01" +#define GPS_MODEL_NAME_CMC_01 "CMC_01" +#define GPS_MODEL_NAME_SCU_01 "SCU_01" +#define GPS_MODEL_NAME_FCU_01 "FCU_01" +#define GPS_MODEL_NAME_MSSB100 "MSSB100" +#define GPS_MODEL_NAME_LNE180SFP "LNE180SFP" +#define GPS_MODEL_NAME_GTS180 "GTS180" +#define GPS_MODEL_NAME_GPS180CSM "GPS180CSM" +#define GPS_MODEL_NAME_GRC181 "GRC181" +#define GPS_MODEL_NAME_N2X180 "N2X180" +#define GPS_MODEL_NAME_GNS181PEX "GNS181PEX" +#define GPS_MODEL_NAME_MDU180 "MDU180" +#define GPS_MODEL_NAME_MDU312 "MDU312" +#define GPS_MODEL_NAME_GPS165 "GPS165" +#define GPS_MODEL_NAME_GNS181_UC "GNS181_UC" +#define GPS_MODEL_NAME_PSX_4GE "PSX_4GE" +#define GPS_MODEL_NAME_RSC180RDU "RSC180RDU" +#define GPS_MODEL_NAME_CPC200 "CPC200" +#define GPS_MODEL_NAME_FDM180M "FDM180M" +#define GPS_MODEL_NAME_LSG180 "LSG180" +#define GPS_MODEL_NAME_GPS190 "GPS190" +#define GPS_MODEL_NAME_GNS181 "GNS181" +#define GPS_MODEL_NAME_PIO180 "PIO180" +#define GPS_MODEL_NAME_FCM180 "FCM180" +#define GPS_MODEL_NAME_TCR180USB "TCR180USB" +#define GPS_MODEL_NAME_SSP100 "SSP100" +#define GPS_MODEL_NAME_GNS165 "GNS165" +#define GPS_MODEL_NAME_RSC180RDMP "RSC180RDMP" +#define GPS_MODEL_NAME_GPS16X "GPS16x" +#define GPS_MODEL_NAME_MSHPS100 "MSHPS100" +#define GPS_MODEL_NAME_BPE_STM "BPE" +#define GPS_MODEL_NAME_VSI180 "VSI180" +#define GPS_MODEL_NAME_GNM181 "GNM181" +#define GPS_MODEL_NAME_RSCRDU_TTL "RSC180RDU_TTL" +#define GPS_MODEL_NAME_RSC2000 "RSC2000" +#define GPS_MODEL_NAME_FCU200 "FCU200" +#define GPS_MODEL_NAME_REL1000_RC "REL1000_RC" +/* + * CARE MUST BE TAKEN that the name string of bus level devices + * is limited to 9 characters. Longer strings will not fit into + * the name field of the PCPS_DEV_TYPE structure. + */ /** @} anchor GPS_MODEL_NAMES */ @@ -992,11 +1296,64 @@ enum GPS_MODEL_CODES GPS_MODEL_NAME_RSC180, \ GPS_MODEL_NAME_LNE_GB, \ GPS_MODEL_NAME_PPG180, \ - GPS_MODEL_NAME_SCG \ + GPS_MODEL_NAME_SCG, \ + GPS_MODEL_NAME_MDU300, \ + GPS_MODEL_NAME_SDI, \ + GPS_MODEL_NAME_FDM180, \ + GPS_MODEL_NAME_SPT, \ + GPS_MODEL_NAME_PZF180, \ + GPS_MODEL_NAME_REL1000, \ + GPS_MODEL_NAME_HPS100, \ + GPS_MODEL_NAME_VSG180, \ + GPS_MODEL_NAME_MSF180, \ + GPS_MODEL_NAME_WWVB180, \ + GPS_MODEL_NAME_CPC180, \ + GPS_MODEL_NAME_CTC100, \ + GPS_MODEL_NAME_TCR180, \ + GPS_MODEL_NAME_LUE180, \ + GPS_MODEL_NAME_CPC_01, \ + GPS_MODEL_NAME_TSU_01, \ + GPS_MODEL_NAME_CMC_01, \ + GPS_MODEL_NAME_SCU_01, \ + GPS_MODEL_NAME_FCU_01, \ + GPS_MODEL_NAME_MSSB100, \ + GPS_MODEL_NAME_LNE180SFP, \ + GPS_MODEL_NAME_GTS180, \ + GPS_MODEL_NAME_GPS180CSM, \ + GPS_MODEL_NAME_GRC181, \ + GPS_MODEL_NAME_N2X180, \ + GPS_MODEL_NAME_GNS181PEX, \ + GPS_MODEL_NAME_MDU180, \ + GPS_MODEL_NAME_MDU312, \ + GPS_MODEL_NAME_GPS165, \ + GPS_MODEL_NAME_GNS181_UC, \ + GPS_MODEL_NAME_PSX_4GE, \ + GPS_MODEL_NAME_RSC180RDU, \ + GPS_MODEL_NAME_CPC200, \ + GPS_MODEL_NAME_FDM180M, \ + GPS_MODEL_NAME_LSG180, \ + GPS_MODEL_NAME_GPS190, \ + GPS_MODEL_NAME_GNS181, \ + GPS_MODEL_NAME_PIO180, \ + GPS_MODEL_NAME_FCM180, \ + GPS_MODEL_NAME_TCR180USB, \ + GPS_MODEL_NAME_SSP100, \ + GPS_MODEL_NAME_GNS165, \ + GPS_MODEL_NAME_RSC180RDMP, \ + GPS_MODEL_NAME_GPS16X, \ + GPS_MODEL_NAME_MSHPS100, \ + GPS_MODEL_NAME_BPE_STM, \ + GPS_MODEL_NAME_VSI180, \ + GPS_MODEL_NAME_GNM181, \ + GPS_MODEL_NAME_RSCRDU_TTL, \ + GPS_MODEL_NAME_RSC2000, \ + GPS_MODEL_NAME_FCU200, \ + GPS_MODEL_NAME_REL1000_RC \ } + /** * @brief Definitions used to classify devices and built-in features * @@ -1008,6 +1365,14 @@ enum GPS_MODEL_CODES /** + * @brief A data type to hold a mask of @ref GPS_BUILTIN_FEATURE_MASKS + * + * @see @ref GPS_BUILTIN_FEATURE_MASKS + */ +typedef uint32_t BUILTIN_FEATURE_MASK; + + +/** * @brief Enumeration of classifiers and built-in features * * @see ::GPS_MODEL_CODES @@ -1022,24 +1387,33 @@ enum GPS_BUILTIN_FEATURE_BITS GPS_BIT_MODEL_IS_DCF_PZF, GPS_BIT_MODEL_IS_MSF, GPS_BIT_MODEL_IS_JJY, - GPS_BIT_MODEL_IS_WWV, - - GPS_BIT_MODEL_IS_LNO, - GPS_BIT_MODEL_IS_SCU, + GPS_BIT_MODEL_IS_WWVB, + GPS_BIT_MODEL_IS_BUS_LVL_DEV, GPS_BIT_MODEL_HAS_BVAR_STAT, GPS_BIT_MODEL_HAS_POS_XYZ, GPS_BIT_MODEL_HAS_POS_LLA, + GPS_BIT_MODEL_HAS_TIME_TTM, GPS_BIT_MODEL_HAS_TZDL, + GPS_BIT_MODEL_HAS_TZCODE, GPS_BIT_MODEL_HAS_ANT_INFO, + GPS_BIT_MODEL_HAS_ENABLE_FLAGS, GPS_BIT_MODEL_HAS_STAT_INFO, - GPS_BIT_MODEL_HAS_ANT_CABLE_LENGTH, - GPS_BIT_MODEL_HAS_GPS_IGNORE_LOCK, - GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV, - GPS_BIT_MODEL_HAS_GNSS_MODE, + GPS_BIT_MODEL_HAS_ANT_CABLE_LEN, + GPS_BIT_MODEL_HAS_SCU_STAT, + GPS_BIT_MODEL_HAS_SV_INFO, + GPS_BIT_MODEL_HAS_UP_CONV, ///< Instead of a standard L1 antenna, a Meinberg antenna/converter can be used with this GNSS device. + GPS_BIT_MODEL_HAS_MBG_OS, ///< This model can be a management CPU for meinbergOS (i.e. v7) + + GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV__REMOVE_THIS, // TODO FIXME - N_GPS_BIT_MODEL +#if 0 //### TODO This has to be discussed + GPS_BIT_MODEL_IS_LNO, + GPS_BIT_MODEL_IS_SCU, +#endif + + N_GPS_BUILTIN_FEATURE_BITS }; @@ -1052,32 +1426,41 @@ enum GPS_BUILTIN_FEATURE_BITS * * @anchor GPS_BUILTIN_FEATURE_MASKS @{ */ -#define GPS_MODEL_IS_GPS ( 1UL << GPS_BIT_MODEL_IS_GPS ) ///< see ::GPS_BIT_MODEL_IS_GPS -#define GPS_MODEL_IS_GNSS ( 1UL << GPS_BIT_MODEL_IS_GNSS ) ///< see ::GPS_BIT_MODEL_IS_GNSS -#define GPS_MODEL_IS_TCR ( 1UL << GPS_BIT_MODEL_IS_TCR ) ///< see ::GPS_BIT_MODEL_IS_TCR -#define GPS_MODEL_IS_DCF_AM ( 1UL << GPS_BIT_MODEL_IS_DCF_AM ) ///< see ::GPS_BIT_MODEL_IS_DCF_AM -#define GPS_MODEL_IS_DCF_PZF ( 1UL << GPS_BIT_MODEL_IS_DCF_PZF ) ///< see ::GPS_BIT_MODEL_IS_DCF_PZF -#define GPS_MODEL_IS_MSF ( 1UL << GPS_BIT_MODEL_IS_MSF ) ///< see ::GPS_BIT_MODEL_IS_MSF -#define GPS_MODEL_IS_JJY ( 1UL << GPS_BIT_MODEL_IS_JJY ) ///< see ::GPS_BIT_MODEL_IS_JJY -#define GPS_MODEL_IS_WWV ( 1UL << GPS_BIT_MODEL_IS_WWV ) ///< see ::GPS_BIT_MODEL_IS_WWV - -#define GPS_MODEL_IS_LNO ( 1UL << GPS_BIT_MODEL_IS_LNO ) ///< see ::GPS_BIT_MODEL_IS_LNO -#define GPS_MODEL_IS_SCU ( 1UL << GPS_BIT_MODEL_IS_SCU ) ///< see ::GPS_BIT_MODEL_IS_SCU - -#define GPS_MODEL_HAS_BVAR_STAT ( 1UL << GPS_BIT_MODEL_HAS_BVAR_STAT ) ///< see ::GPS_BIT_MODEL_HAS_BVAR_STAT -#define GPS_MODEL_HAS_POS_XYZ ( 1UL << GPS_BIT_MODEL_HAS_POS_XYZ ) ///< see ::GPS_BIT_MODEL_HAS_POS_XYZ -#define GPS_MODEL_HAS_POS_LLA ( 1UL << GPS_BIT_MODEL_HAS_POS_LLA ) ///< see ::GPS_BIT_MODEL_HAS_POS_LLA -#define GPS_MODEL_HAS_TZDL ( 1UL << GPS_BIT_MODEL_HAS_TZDL ) ///< see ::GPS_BIT_MODEL_HAS_TZDL -#define GPS_MODEL_HAS_ANT_INFO ( 1UL << GPS_BIT_MODEL_HAS_ANT_INFO ) ///< see ::GPS_BIT_MODEL_HAS_ANT_INFO -#define GPS_MODEL_HAS_ENABLE_FLAGS ( 1UL << GPS_BIT_MODEL_HAS_ENABLE_FLAGS ) ///< see ::GPS_BIT_MODEL_HAS_ENABLE_FLAGS -#define GPS_MODEL_HAS_STAT_INFO ( 1UL << GPS_BIT_MODEL_HAS_STAT_INFO ) ///< see ::GPS_BIT_MODEL_HAS_STAT_INFO -#define GPS_MODEL_HAS_ANT_CABLE_LENGTH ( 1UL << GPS_BIT_MODEL_HAS_ANT_CABLE_LENGTH ) ///< see ::GPS_BIT_MODEL_HAS_ANT_CABLE_LENGTH -#define GPS_MODEL_HAS_GPS_IGNORE_LOCK ( 1UL << GPS_BIT_MODEL_HAS_GPS_IGNORE_LOCK ) ///< see ::GPS_BIT_MODEL_HAS_GPS_IGNORE_LOCK -#define GPS_MODEL_HAS_XMR_HOLDOVER_INTV ( 1UL << GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV ) ///< see ::GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV - -#define GPS_MODEL_HAS_GNSS_MODE ( 1UL << GPS_BIT_MODEL_HAS_GNSS_MODE ) ///< see ::GPS_BIT_MODEL_HAS_GNSS_MODE - -//##+++++ TODO: should we use an extra flag? +#define GPS_MODEL_IS_GPS ( 1UL << GPS_BIT_MODEL_IS_GPS ) ///< See ::GPS_BIT_MODEL_IS_GPS +#define GPS_MODEL_IS_GNSS ( 1UL << GPS_BIT_MODEL_IS_GNSS ) ///< See ::GPS_BIT_MODEL_IS_GNSS +#define GPS_MODEL_IS_TCR ( 1UL << GPS_BIT_MODEL_IS_TCR ) ///< See ::GPS_BIT_MODEL_IS_TCR +#define GPS_MODEL_IS_DCF_AM ( 1UL << GPS_BIT_MODEL_IS_DCF_AM ) ///< See ::GPS_BIT_MODEL_IS_DCF_AM +#define GPS_MODEL_IS_DCF_PZF ( 1UL << GPS_BIT_MODEL_IS_DCF_PZF ) ///< See ::GPS_BIT_MODEL_IS_DCF_PZF +#define GPS_MODEL_IS_MSF ( 1UL << GPS_BIT_MODEL_IS_MSF ) ///< See ::GPS_BIT_MODEL_IS_MSF +#define GPS_MODEL_IS_JJY ( 1UL << GPS_BIT_MODEL_IS_JJY ) ///< See ::GPS_BIT_MODEL_IS_JJY +#define GPS_MODEL_IS_WWVB ( 1UL << GPS_BIT_MODEL_IS_WWVB ) ///< See ::GPS_BIT_MODEL_IS_WWVB + +#define GPS_MODEL_IS_BUS_LVL_DEV ( 1UL << GPS_BIT_MODEL_IS_BUS_LVL_DEV ) ///< See ::GPS_BIT_MODEL_IS_BUS_LVL_DEV +#define GPS_MODEL_HAS_BVAR_STAT ( 1UL << GPS_BIT_MODEL_HAS_BVAR_STAT ) ///< See ::GPS_BIT_MODEL_HAS_BVAR_STAT +#define GPS_MODEL_HAS_POS_XYZ ( 1UL << GPS_BIT_MODEL_HAS_POS_XYZ ) ///< See ::GPS_BIT_MODEL_HAS_POS_XYZ +#define GPS_MODEL_HAS_POS_LLA ( 1UL << GPS_BIT_MODEL_HAS_POS_LLA ) ///< See ::GPS_BIT_MODEL_HAS_POS_LLA +#define GPS_MODEL_HAS_TIME_TTM ( 1UL << GPS_BIT_MODEL_HAS_TIME_TTM ) ///< See ::GPS_BIT_MODEL_HAS_TIME_TTM +#define GPS_MODEL_HAS_TZDL ( 1UL << GPS_BIT_MODEL_HAS_TZDL ) ///< See ::GPS_BIT_MODEL_HAS_TZDL +#define GPS_MODEL_HAS_TZCODE ( 1UL << GPS_BIT_MODEL_HAS_TZCODE ) ///< See ::GPS_BIT_MODEL_HAS_TZCODE +#define GPS_MODEL_HAS_ANT_INFO ( 1UL << GPS_BIT_MODEL_HAS_ANT_INFO ) ///< See ::GPS_BIT_MODEL_HAS_ANT_INFO + +#define GPS_MODEL_HAS_ENABLE_FLAGS ( 1UL << GPS_BIT_MODEL_HAS_ENABLE_FLAGS ) ///< See ::GPS_BIT_MODEL_HAS_ENABLE_FLAGS +#define GPS_MODEL_HAS_STAT_INFO ( 1UL << GPS_BIT_MODEL_HAS_STAT_INFO ) ///< See ::GPS_BIT_MODEL_HAS_STAT_INFO +#define GPS_MODEL_HAS_ANT_CABLE_LEN ( 1UL << GPS_BIT_MODEL_HAS_ANT_CABLE_LEN ) ///< See ::GPS_BIT_MODEL_HAS_ANT_CABLE_LEN +#define GPS_MODEL_HAS_SCU_STAT ( 1UL << GPS_BIT_MODEL_HAS_SCU_STAT ) ///< See ::GPS_BIT_MODEL_HAS_SCU_STAT +#define GPS_MODEL_HAS_SV_INFO ( 1UL << GPS_BIT_MODEL_HAS_SV_INFO ) ///< See ::GPS_BIT_MODEL_HAS_SV_INFO +#define GPS_MODEL_HAS_UP_CONV ( 1UL << GPS_BIT_MODEL_HAS_UP_CONV ) ///< See ::GPS_BIT_MODEL_HAS_UP_CONV +#define GPS_MODEL_HAS_MBG_OS ( 1UL << GPS_BIT_MODEL_HAS_MBG_OS ) ///< See ::GPS_BIT_MODEL_HAS_MBG_OS + +#if 0 // ### TODO This has to be discussed + #define GPS_MODEL_IS_LNO ( 1UL << GPS_BIT_MODEL_IS_LNO ) ///< See ::GPS_BIT_MODEL_IS_LNO + #define GPS_MODEL_IS_SCU ( 1UL << GPS_BIT_MODEL_IS_SCU ) ///< See ::GPS_BIT_MODEL_IS_SCU +#endif + +// ### TODO FIXME do we need the next one? Should be obsolete +// #define GPS_MODEL_HAS_XMR_HOLDOVER_INTV ( 1UL << GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV ) ///< See ::GPS_BIT_MODEL_HAS_XMR_HOLDOVER_INTV + +//### TODO: should we use an extra flag? #define GPS_MODEL_HAS_POS ( GPS_MODEL_HAS_POS_XYZ | GPS_MODEL_HAS_POS_LLA ) /** @} anchor GPS_BUILTIN_FEATURE_MASKS */ @@ -1095,7 +1478,6 @@ enum GPS_BUILTIN_FEATURE_BITS #define GPS_MODEL_HAS_AUTO_OFF // -- #define GPS_MODEL_HAS_SW_REV // deprecated, use only if ri not supported #define GPS_MODEL_HAS_BVAR_STAT // req -#define GPS_MODEL_HAS_TIME // ? #define GPS_MODEL_HAS_POS_XYZ // GPS_MODEL_IS_GPS, GPS_MODEL_HAS_POS, GPS_MODEL_HAS_POS_XYZ ? #define GPS_MODEL_HAS_POS_LLA // GPS_MODEL_IS_GPS, GPS_MODEL_HAS_POS, GPS_MODEL_HAS_POS_LLA ? #define GPS_MODEL_HAS_TZDL // req @@ -1107,7 +1489,7 @@ enum GPS_BUILTIN_FEATURE_BITS #define GPS_MODEL_HAS_STAT_INFO // req #define GPS_MODEL_HAS_SWITCH_PARMS // deprecated, use ... #define GPS_MODEL_HAS_STRING_PARMS // deprecated, use ... -#define GPS_MODEL_HAS_ANT_CABLE_LENGTH // GPS_MODEL_IS_GPS, also GNSS, or req? +#define GPS_MODEL_HAS_ANT_CABLE_LEN // GPS_MODEL_IS_GPS, also GNSS, or req? #define GPS_MODEL_HAS_SYNC_OUTAGE_DELAY // custom #define GPS_MODEL_HAS_PULSE_INFO // custom #define GPS_MODEL_HAS_OPT_FEATURES // deprecated, use ri @@ -1124,78 +1506,75 @@ enum GPS_BUILTIN_FEATURE_BITS #define GPS_MODEL_HAS_ROM_CSUM // ? #define GPS_MODEL_HAS_MULTI_REF_STATUS // ri ... #define GPS_MODEL_HAS_RCV_TIMEOUT // ri ... -#define GPS_MODEL_HAS_IGNORE_LOCK // ? #define GPS_MODEL_HAS_IRIG_RX_SETTINGS // ri ... #define GPS_MODEL_HAS_IRIG_RX_INFO // ri ... #define GPS_MODEL_HAS_REF_OFFS // ri ... -#define GPS_MODEL_HAS_DEBUG_STATUS // -#define GPS_MODEL_HAS_XMR_SETTINGS_IDX // -#define GPS_MODEL_HAS_XMR_INFO_IDX // -#define GPS_MODEL_HAS_XMR_STATUS_IDX // -#define GPS_MODEL_HAS_OPT_SETTINGS // -#define GPS_MODEL_HAS_OPT_INFO // -#define GPS_MODEL_HAS_CLR_UCAP_BUFF // -#define GPS_MODEL_HAS_TIME_SCALE // -#define GPS_MODEL_HAS_NAV_ENG_SETTINGS // -#define GPS_MODEL_HAS_RAW_IRIG_DATA // -#define GPS_MODEL_HAS_GPIO_CFG_LIMITS // -#define GPS_MODEL_HAS_GPIO_INFO_IDX // -#define GPS_MODEL_HAS_GPIO_SETTINGS_IDX // -#define GPS_MODEL_HAS_XMR_INSTANCES // -#define GPS_MODEL_HAS_CLR_EVT_LOG // -#define GPS_MODEL_HAS_NUM_EVT_LOG_ENTRIES // -#define GPS_MODEL_HAS_FIRST_EVT_LOG_ENTRY // -#define GPS_MODEL_HAS_NEXT_EVT_LOG_ENTRY // -#define GPS_MODEL_HAS_LNO_STATUS // -#define GPS_MODEL_HAS_IMS_STATE // -#define GPS_MODEL_HAS_IMS_SENSOR_STATE_IDX // -#define GPS_MODEL_HAS_XMR_HOLDOVER_INTV // -#define GPS_MODEL_HAS_HAVEQUICK_RX_SETTINGS // -#define GPS_MODEL_HAS_HAVEQUICK_RX_INFO // -#define GPS_MODEL_HAS_HAVEQUICK_TX_SETTINGS // -#define GPS_MODEL_HAS_HAVEQUICK_TX_INFO // -#define GPS_MODEL_HAS_PTP_CFG // -#define GPS_MODEL_HAS_PTP_STATE // -#define GPS_MODEL_HAS_PTP_UC_MASTER_CFG_LIMITS // -#define GPS_MODEL_HAS_PTP_UC_MASTER_CFG // -#define GPS_MODEL_HAS_NTP_GLB_CFG // -#define GPS_MODEL_HAS_NTP_CLNT_MODE_CFG // -#define GPS_MODEL_HAS_NTP_SRV_MODE_CFG // -#define GPS_MODEL_HAS_NTP_PEER_SETTINGS_IDX // -#define GPS_MODEL_HAS_NTP_SYS_STATE // -#define GPS_MODEL_HAS_NTP_PEER_STATE_IDX // -#define GPS_MODEL_HAS_SHS // -#define GPS_MODEL_HAS_SHS_STATUS // -#define GPS_MODEL_HAS_NET_GLB_CFG // -#define GPS_MODEL_HAS_NET_DNS_SRVR // -#define GPS_MODEL_HAS_NET_DNS_SRC_DOM // -#define GPS_MODEL_HAS_NET_STAT_DNS_SRVR // -#define GPS_MODEL_HAS_NET_STAT_DNS_SRC_DOM // -#define GPS_MODEL_HAS_GNSS_SAT_INFO_IDX // - -#define GPS_MODEL_HAS_CFGH // -#define GPS_MODEL_HAS_ALM // -#define GPS_MODEL_HAS_EPH // -#define GPS_MODEL_HAS_UTC // -#define GPS_MODEL_HAS_IONO // -#define GPS_MODEL_HAS_ASCII_MSG // - -#define GPS_MODEL_HAS_GLNS_ALM // -#define GPS_MODEL_HAS_GNSS_SAT_INFO // -#define GPS_MODEL_HAS_GNSS_MODE // - -#define GPS_MODEL_HAS_IP4_SETTINGS // -#define GPS_MODEL_HAS_LAN_IF_INFO // -#define GPS_MODEL_HAS_IP4_STATE // - -#define GPS_MODEL_HAS_SCU_STAT // - -#define GPS_MODEL_HAS_CRYPTED_PACKET // -#define GPS_MODEL_HAS_CRYPTED_RAW_PACKET // - -#define GPS_MODEL_HAS_SECU_INFO // -#define GPS_MODEL_HAS_SECU_SETTINGS // -#define GPS_MODEL_HAS_SECU_PUBLIC_KEY // +#define GPS_MODEL_HAS_DEBUG_STATUS // +#define GPS_MODEL_HAS_XMR_SETTINGS_IDX // +#define GPS_MODEL_HAS_XMR_INFO_IDX // +#define GPS_MODEL_HAS_XMR_STATUS_IDX // +#define GPS_MODEL_HAS_OPT_SETTINGS // +#define GPS_MODEL_HAS_OPT_INFO // +#define GPS_MODEL_HAS_CLR_UCAP_BUFF // +#define GPS_MODEL_HAS_TIME_SCALE // +#define GPS_MODEL_HAS_NAV_ENG_SETTINGS // +#define GPS_MODEL_HAS_RAW_IRIG_DATA // +#define GPS_MODEL_HAS_GPIO_CFG_LIMITS // +#define GPS_MODEL_HAS_GPIO_INFO_IDX // +#define GPS_MODEL_HAS_GPIO_SETTINGS_IDX // +#define GPS_MODEL_HAS_XMR_INSTANCES // +#define GPS_MODEL_HAS_CLR_EVT_LOG // +#define GPS_MODEL_HAS_NUM_EVT_LOG_ENTRIES // +#define GPS_MODEL_HAS_FIRST_EVT_LOG_ENTRY // +#define GPS_MODEL_HAS_NEXT_EVT_LOG_ENTRY // +#define GPS_MODEL_HAS_LNO_STATUS // +#define GPS_MODEL_HAS_IMS_STATE // +#define GPS_MODEL_HAS_IMS_SENSOR_STATE_IDX // +#define GPS_MODEL_HAS_XMR_HOLDOVER_INTV // +#define GPS_MODEL_HAS_HAVEQUICK_RX_SETTINGS // +#define GPS_MODEL_HAS_HAVEQUICK_RX_INFO // +#define GPS_MODEL_HAS_HAVEQUICK_TX_SETTINGS // +#define GPS_MODEL_HAS_HAVEQUICK_TX_INFO // +#define GPS_MODEL_HAS_PTP_CFG // +#define GPS_MODEL_HAS_PTP_STATE // +#define GPS_MODEL_HAS_PTP_UC_MASTER_CFG_LIMITS // +#define GPS_MODEL_HAS_PTP_UC_MASTER_CFG // +#define GPS_MODEL_HAS_NTP_GLB_CFG // +#define GPS_MODEL_HAS_NTP_CLNT_MODE_CFG // +#define GPS_MODEL_HAS_NTP_SRV_MODE_CFG // +#define GPS_MODEL_HAS_NTP_PEER_SETTINGS_IDX // +#define GPS_MODEL_HAS_NTP_SYS_STATE // +#define GPS_MODEL_HAS_NTP_PEER_STATE_IDX // +#define GPS_MODEL_HAS_SHS // +#define GPS_MODEL_HAS_SHS_STATUS // +#define GPS_MODEL_HAS_NET_GLB_CFG // +#define GPS_MODEL_HAS_NET_DNS_SRVR // +#define GPS_MODEL_HAS_NET_DNS_SRCH_DOM // +#define GPS_MODEL_HAS_NET_STAT_DNS_SRVR // +#define GPS_MODEL_HAS_NET_STAT_DNS_SRCH_DOM // +#define GPS_MODEL_HAS_GNSS_SAT_INFO_IDX // + +#define GPS_MODEL_HAS_CFGH // +#define GPS_MODEL_HAS_ALM // +#define GPS_MODEL_HAS_EPH // +#define GPS_MODEL_HAS_UTC // +#define GPS_MODEL_HAS_IONO // +#define GPS_MODEL_HAS_ASCII_MSG // + +#define GPS_MODEL_HAS_GLNS_ALM // +#define GPS_MODEL_HAS_GNSS_SAT_INFO // +//#define GPS_MODEL_HAS_GNSS_MODE // + +#define GPS_MODEL_HAS_IP4_SETTINGS // +#define GPS_MODEL_HAS_LAN_IF_INFO // +#define GPS_MODEL_HAS_IP4_STATE // + +#define GPS_MODEL_HAS_CRYPTED_PACKET // +#define GPS_MODEL_HAS_CRYPTED_RAW_PACKET // + +#define GPS_MODEL_HAS_SECU_INFO // +#define GPS_MODEL_HAS_SECU_SETTINGS // +#define GPS_MODEL_HAS_SECU_PUBLIC_KEY // #endif //##++ more potential builtin features and classifiers @@ -1203,6 +1582,9 @@ enum GPS_BUILTIN_FEATURE_BITS /** * @brief Common builtin features of all GPS receivers + * + * @see ::BUILTIN_FEAT_GPS_BUS_LVL + * @see ::BUILTIN_FEAT_GNSS */ #define BUILTIN_FEAT_GPS \ ( \ @@ -1210,11 +1592,13 @@ enum GPS_BUILTIN_FEATURE_BITS GPS_MODEL_HAS_BVAR_STAT | \ GPS_MODEL_HAS_POS_XYZ | \ GPS_MODEL_HAS_POS_LLA | \ + GPS_MODEL_HAS_TIME_TTM | \ GPS_MODEL_HAS_TZDL | \ GPS_MODEL_HAS_ANT_INFO | \ GPS_MODEL_HAS_ENABLE_FLAGS | \ GPS_MODEL_HAS_STAT_INFO | \ - GPS_MODEL_HAS_ANT_CABLE_LENGTH \ + GPS_MODEL_HAS_ANT_CABLE_LEN | \ + GPS_MODEL_HAS_SV_INFO \ ) @@ -1223,17 +1607,198 @@ enum GPS_BUILTIN_FEATURE_BITS * * GNSS includes GPS but optionally other satellite systems, * and the associated API. + * + * @see ::BUILTIN_FEAT_GNSS_BUS_LVL + * @see ::BUILTIN_FEAT_GPS */ #define BUILTIN_FEAT_GNSS \ ( \ BUILTIN_FEAT_GPS | \ - GPS_MODEL_IS_GNSS | \ - GPS_MODEL_HAS_GNSS_MODE \ + GPS_MODEL_IS_GNSS \ +) + + + +/** + * @brief Common builtin features of all simple TCR devices + */ +#define BUILTIN_FEAT_TCR_1 \ +( \ + GPS_MODEL_IS_TCR \ +) + + +/** + * @brief Common builtin features of all enhanced TCR devices + */ +#define BUILTIN_FEAT_TCR_2 \ +( \ + GPS_MODEL_IS_TCR | \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ANT_INFO | \ + GPS_MODEL_HAS_ENABLE_FLAGS \ ) /** + * @brief Common builtin features of all simple DCF77 AM receivers + */ +#define BUILTIN_FEAT_DCF_1 \ +( \ + GPS_MODEL_IS_DCF_AM | \ + GPS_MODEL_HAS_TZCODE \ +) + + +/** + * @brief Common builtin features of all enhanced DCF77 AM receivers + */ +#define BUILTIN_FEAT_DCF_2 \ +( \ + GPS_MODEL_IS_DCF_AM | \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ANT_INFO | \ + GPS_MODEL_HAS_ENABLE_FLAGS \ +) + + +/** + * @brief Common builtin features of all simple DCF77 PZF receivers + */ +#define BUILTIN_FEAT_DCF_PZF_1 \ +( \ + GPS_MODEL_IS_DCF_PZF | \ + GPS_MODEL_HAS_TZCODE \ +) + + +/** + * @brief Common builtin features of all enhanced DCF77 PZF receivers + */ +#define BUILTIN_FEAT_DCF_PZF_2 \ +( \ + GPS_MODEL_IS_DCF_AM | \ + GPS_MODEL_IS_DCF_PZF | \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ANT_INFO | \ + GPS_MODEL_HAS_ENABLE_FLAGS \ +) + + + +/** + * @brief Common builtin features of all simple MSF receivers + */ +#define BUILTIN_FEAT_MSF_1 \ +( \ + GPS_MODEL_IS_MSF | \ + GPS_MODEL_HAS_TZCODE \ +) + + +/** + * @brief Common builtin features of all enhanced MSF receivers + */ +#define BUILTIN_FEAT_MSF_2 \ +( \ + GPS_MODEL_IS_MSF | \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ANT_INFO | \ + GPS_MODEL_HAS_ENABLE_FLAGS \ +) + + + +/** + * @brief Common builtin features of all simple WWVB receivers + */ +#define BUILTIN_FEAT_WVB_1 \ +( \ + GPS_MODEL_IS_WWVB | \ + GPS_MODEL_HAS_TZCODE \ +) + + +/** + * @brief Common builtin features of all enhanced WWVB receivers + */ +#define BUILTIN_FEAT_WVB_2 \ +( \ + GPS_MODEL_IS_WWVB | \ + GPS_MODEL_HAS_TZDL \ +) + + + +/** + * @brief Common builtin features of all simple JJY receivers + */ +#define BUILTIN_FEAT_JJY_1 \ +( \ + GPS_MODEL_IS_JJY | \ + GPS_MODEL_HAS_TZCODE \ +) + + + +/** + * @brief Common builtin features of all N2X devices + */ +#define BUILTIN_FEAT_COMM_N2X \ +( \ + GPS_MODEL_HAS_TIME_TTM | \ + GPS_MODEL_HAS_TZDL | \ + GPS_MODEL_HAS_ENABLE_FLAGS \ +) + + + +/** + * @brief Common builtin features of all bus-level GPS receivers + */ +#define BUILTIN_FEAT_GPS_BUS_LVL ( BUILTIN_FEAT_GPS | GPS_MODEL_IS_BUS_LVL_DEV ) + + +/** + * @brief Common builtin features of all bus-level GNSS receivers + */ +#define BUILTIN_FEAT_GNSS_BUS_LVL ( BUILTIN_FEAT_GNSS | GPS_MODEL_IS_BUS_LVL_DEV ) + + +/** + * @brief Common builtin features of all simple, bus-level TCR devices + */ +#define BUILTIN_FEAT_TCR_1_BUS_LVL ( BUILTIN_FEAT_TCR_1 | GPS_MODEL_IS_BUS_LVL_DEV ) + +/** + * @brief Common builtin features of all enhanced, bus-level TCR devices + */ +#define BUILTIN_FEAT_TCR_2_BUS_LVL ( BUILTIN_FEAT_TCR_2 | GPS_MODEL_IS_BUS_LVL_DEV ) + + +/** + * @brief Common builtin features of all simple, bus-level DCF77 AM receivers + */ +#define BUILTIN_FEAT_DCF_1_BUS_LVL ( BUILTIN_FEAT_DCF_1 | GPS_MODEL_IS_BUS_LVL_DEV ) + +/** + * @brief Common builtin features of all enhanced, bus-level DCF77 AM receivers + */ +#define BUILTIN_FEAT_DCF_2_BUS_LVL ( BUILTIN_FEAT_DCF_2 | GPS_MODEL_IS_BUS_LVL_DEV ) + +/** + * @brief Common builtin features of all enhanced, bus-level DCF77 PZF receivers + */ +#define BUILTIN_FEAT_DCF_PZF_2_BUS_LVL ( BUILTIN_FEAT_DCF_PZF_2 | GPS_MODEL_IS_BUS_LVL_DEV ) + + + +/** * @brief Definitions of builtin features per device type * * @see ::GPS_MODEL_CODES @@ -1244,63 +1809,127 @@ enum GPS_BUILTIN_FEATURE_BITS #define BUILTIN_FEAT_GPS166 ( BUILTIN_FEAT_GPS ) #define BUILTIN_FEAT_GPS167 ( BUILTIN_FEAT_GPS ) #define BUILTIN_FEAT_GPS167SV ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_GPS167PC ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_GPS167PCI ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GPS167PC ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_GPS167PCI ( BUILTIN_FEAT_GPS_BUS_LVL ) #define BUILTIN_FEAT_GPS163 ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_GPS168PCI ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GPS168PCI ( BUILTIN_FEAT_GPS_BUS_LVL ) #define BUILTIN_FEAT_GPS161 ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_GPS169PCI ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_TCR167PCI ( 0 ) +#define BUILTIN_FEAT_GPS169PCI ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_TCR167PCI ( BUILTIN_FEAT_TCR_2_BUS_LVL ) #define BUILTIN_FEAT_GPS164 ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_GPS170PCI ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_PZF511 ( 0 ) +#define BUILTIN_FEAT_GPS170PCI ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_PZF511 ( BUILTIN_FEAT_DCF_PZF_1 ) #define BUILTIN_FEAT_GPS170 ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_TCR511 ( 0 ) -#define BUILTIN_FEAT_AM511 ( 0 ) -#define BUILTIN_FEAT_MSF511 ( 0 ) -#define BUILTIN_FEAT_GRC170 ( 0 ) -#define BUILTIN_FEAT_GPS170PEX ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_TCR511 ( BUILTIN_FEAT_TCR_1_BUS_LVL | GPS_MODEL_HAS_TIME_TTM ) //### TODO Or full TCR_2? +#define BUILTIN_FEAT_AM511 ( BUILTIN_FEAT_DCF_1 ) +#define BUILTIN_FEAT_MSF511 ( BUILTIN_FEAT_MSF_1 ) +#define BUILTIN_FEAT_GRC170 ( BUILTIN_FEAT_GNSS ) +#define BUILTIN_FEAT_GPS170PEX ( BUILTIN_FEAT_GPS_BUS_LVL ) #define BUILTIN_FEAT_GPS162 ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_PTP270PEX ( 0 ) -#define BUILTIN_FEAT_FRC511PEX ( 0 ) -#define BUILTIN_FEAT_GEN170 ( 0 ) -#define BUILTIN_FEAT_TCR170PEX ( 0 ) -#define BUILTIN_FEAT_WWVB511 ( 0 ) +#define BUILTIN_FEAT_PTP270PEX ( GPS_MODEL_IS_BUS_LVL_DEV ) +#define BUILTIN_FEAT_FRC511PEX ( GPS_MODEL_IS_BUS_LVL_DEV ) +#define BUILTIN_FEAT_GEN170 ( GPS_MODEL_HAS_TIME_TTM ) +#define BUILTIN_FEAT_TCR170PEX ( BUILTIN_FEAT_TCR_2_BUS_LVL ) +#define BUILTIN_FEAT_WWVB511 ( BUILTIN_FEAT_WVB_1 ) #define BUILTIN_FEAT_MGR170 ( 0 ) -#define BUILTIN_FEAT_JJY511 ( 0 ) -#define BUILTIN_FEAT_PZF600 ( 0 ) -#define BUILTIN_FEAT_TCR600 ( 0 ) +#define BUILTIN_FEAT_JJY511 ( BUILTIN_FEAT_JJY_1 ) +#define BUILTIN_FEAT_PZF600 ( BUILTIN_FEAT_DCF_PZF_1 ) //### TODO Or full PZF_2? +#define BUILTIN_FEAT_TCR600 ( BUILTIN_FEAT_TCR_1 | GPS_MODEL_HAS_TIME_TTM ) //### TODO Or full TCR_2? #define BUILTIN_FEAT_GPS180 ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_GLN170 ( 0 ) -#define BUILTIN_FEAT_GPS180PEX ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_TCR180PEX ( 0 ) -#define BUILTIN_FEAT_PZF180PEX ( 0 ) +#define BUILTIN_FEAT_GLN170 ( BUILTIN_FEAT_GNSS) +#define BUILTIN_FEAT_GPS180PEX ( BUILTIN_FEAT_GPS_BUS_LVL ) +#define BUILTIN_FEAT_TCR180PEX ( BUILTIN_FEAT_TCR_2_BUS_LVL ) +#define BUILTIN_FEAT_PZF180PEX ( BUILTIN_FEAT_DCF_PZF_2_BUS_LVL ) #define BUILTIN_FEAT_MGR180 ( 0 ) -#define BUILTIN_FEAT_MSF600 ( 0 ) -#define BUILTIN_FEAT_WWVB600 ( 0 ) -#define BUILTIN_FEAT_JJY600 ( 0 ) +#define BUILTIN_FEAT_MSF600 ( BUILTIN_FEAT_MSF_1 ) //### TODO Or full MSF_2? +#define BUILTIN_FEAT_WWVB600 ( BUILTIN_FEAT_WVB_1 ) //### TODO Or full WVB_2? +#define BUILTIN_FEAT_JJY600 ( BUILTIN_FEAT_JJY_1 ) //### TODO Or full JJY_2? #define BUILTIN_FEAT_GPS180HS ( BUILTIN_FEAT_GPS ) -#define BUILTIN_FEAT_GPS180AMC ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GPS180AMC ( BUILTIN_FEAT_GPS_BUS_LVL ) #define BUILTIN_FEAT_ESI180 ( 0 ) #define BUILTIN_FEAT_CPE180 ( 0 ) #define BUILTIN_FEAT_LNO180 ( 0 ) -#define BUILTIN_FEAT_GRC180 ( 0 ) +#define BUILTIN_FEAT_GRC180 ( BUILTIN_FEAT_GNSS ) #define BUILTIN_FEAT_LIU ( 0 ) -#define BUILTIN_FEAT_DCF600HS ( 0 ) -#define BUILTIN_FEAT_DCF600RS ( 0 ) +#define BUILTIN_FEAT_DCF600HS ( BUILTIN_FEAT_DCF_2 ) //### TODO +#define BUILTIN_FEAT_DCF600RS ( BUILTIN_FEAT_DCF_2 ) //### TODO #define BUILTIN_FEAT_MRI ( 0 ) #define BUILTIN_FEAT_BPE ( 0 ) -#define BUILTIN_FEAT_GLN180PEX ( BUILTIN_FEAT_GNSS ) -#define BUILTIN_FEAT_N2X ( 0 ) -#define BUILTIN_FEAT_RSC180 ( 0 ) +#define BUILTIN_FEAT_GLN180PEX ( BUILTIN_FEAT_GNSS_BUS_LVL ) +#define BUILTIN_FEAT_N2X ( BUILTIN_FEAT_COMM_N2X ) +#define BUILTIN_FEAT_RSC180 ( GPS_MODEL_HAS_SCU_STAT ) #define BUILTIN_FEAT_LNE_GB ( 0 ) #define BUILTIN_FEAT_PPG180 ( 0 ) #define BUILTIN_FEAT_SCG ( 0 ) +#define BUILTIN_FEAT_MDU300 ( 0 ) +#define BUILTIN_FEAT_SDI ( 0 ) +#define BUILTIN_FEAT_FDM180 ( GPS_MODEL_HAS_TZDL | GPS_MODEL_HAS_ENABLE_FLAGS ) +#define BUILTIN_FEAT_SPT ( 0 ) +#define BUILTIN_FEAT_PZF180 ( BUILTIN_FEAT_DCF_PZF_2 ) +#define BUILTIN_FEAT_REL1000 ( 0 ) +#define BUILTIN_FEAT_HPS100 ( 0 ) +#define BUILTIN_FEAT_VSG180 ( GPS_MODEL_HAS_TZDL ) +#define BUILTIN_FEAT_MSF180 ( BUILTIN_FEAT_MSF_2 ) +#define BUILTIN_FEAT_WWVB180 ( BUILTIN_FEAT_WVB_2 ) +#define BUILTIN_FEAT_CPC180 ( 0 ) +#define BUILTIN_FEAT_CTC100 ( GPS_MODEL_HAS_MBG_OS ) +#define BUILTIN_FEAT_TCR180 ( BUILTIN_FEAT_TCR_2 ) +#define BUILTIN_FEAT_LUE180 ( 0 ) +#define BUILTIN_FEAT_CPC_01 ( 0 ) +#define BUILTIN_FEAT_TSU_01 ( 0 ) +#define BUILTIN_FEAT_CMC_01 ( 0 ) +#define BUILTIN_FEAT_SCU_01 ( 0 ) +#define BUILTIN_FEAT_FCU_01 ( 0 ) +#define BUILTIN_FEAT_MSSB100 ( GPS_MODEL_HAS_MBG_OS ) +#define BUILTIN_FEAT_LNE180SFP ( 0 ) +#define BUILTIN_FEAT_GTS180 ( 0 ) +#define BUILTIN_FEAT_GPS180CSM ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GRC181 ( BUILTIN_FEAT_GNSS ) +#define BUILTIN_FEAT_N2X180 ( BUILTIN_FEAT_COMM_N2X ) +#define BUILTIN_FEAT_GNS181PEX ( BUILTIN_FEAT_GNSS_BUS_LVL ) +#define BUILTIN_FEAT_MDU180 ( GPS_MODEL_HAS_SCU_STAT ) +#define BUILTIN_FEAT_MDU312 ( 0 ) +#define BUILTIN_FEAT_GPS165 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GNS181_UC ( BUILTIN_FEAT_GNSS | GPS_MODEL_HAS_UP_CONV ) +#define BUILTIN_FEAT_PSX_4GE ( GPS_MODEL_HAS_MBG_OS ) +#define BUILTIN_FEAT_RSC180RDU ( GPS_MODEL_HAS_SCU_STAT ) +#define BUILTIN_FEAT_CPC200 ( 0 ) +#define BUILTIN_FEAT_FDM180M ( GPS_MODEL_HAS_TZDL | GPS_MODEL_HAS_ENABLE_FLAGS ) +#define BUILTIN_FEAT_LSG180 ( 0 ) +#define BUILTIN_FEAT_GPS190 ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_GNS181 ( BUILTIN_FEAT_GNSS ) +#define BUILTIN_FEAT_PIO180 ( 0 ) +#define BUILTIN_FEAT_FCM180 ( 0 ) +#define BUILTIN_FEAT_TCR180USB ( 0 ) +#define BUILTIN_FEAT_SSP100 ( GPS_MODEL_HAS_MBG_OS ) +#define BUILTIN_FEAT_GNS165 ( BUILTIN_FEAT_GNSS ) +#define BUILTIN_FEAT_RSC180RDMP ( GPS_MODEL_HAS_SCU_STAT ) +#define BUILTIN_FEAT_GPS16X ( BUILTIN_FEAT_GPS ) +#define BUILTIN_FEAT_MSHPS100 ( GPS_MODEL_HAS_MBG_OS ) +#define BUILTIN_FEAT_BPE_STM ( 0 ) +#define BUILTIN_FEAT_VSI180 ( 0 ) +#define BUILTIN_FEAT_GNM181 ( BUILTIN_FEAT_GNSS ) +#define BUILTIN_FEAT_RSCRDU_TTL ( GPS_MODEL_HAS_SCU_STAT ) +#define BUILTIN_FEAT_RSC2000 ( GPS_MODEL_HAS_SCU_STAT ) +#define BUILTIN_FEAT_FCU200 ( 0 ) +#define BUILTIN_FEAT_REL1000_RC ( BUILTIN_FEAT_REL1000 ) + +/** + * @brief Feature mask used for legacy devices + * + * This code is used to set builtin feature flags + * legacy devices not listed here, so we can simply + * search for ::BUILTIN_FEAT_UNDEFINED to identify + * such devices. The numeric value is just 0, though. + */ +#define BUILTIN_FEAT_UNDEFINED ( 0 ) /** @} anchor GPS_MODEL_BUILTIN_FEATURE_MASKS */ +#if !defined( MBG_TGT_DOS ) + /** * @brief Initializer for a table of built-in features per device * @@ -1309,70 +1938,377 @@ enum GPS_BUILTIN_FEATURE_BITS * @see ::GPS_MODEL_CODES * @see @ref GPS_MODEL_BUILTIN_FEATURE_MASKS */ -#define GPS_MODEL_BUILTIN_FEATURES \ -{ \ - { GPS_MODEL_GPS166, BUILTIN_FEAT_GPS166 }, \ - { GPS_MODEL_GPS167, BUILTIN_FEAT_GPS167 }, \ - { GPS_MODEL_GPS167SV, BUILTIN_FEAT_GPS167SV }, \ - { GPS_MODEL_GPS167PC, BUILTIN_FEAT_GPS167PC }, \ - { GPS_MODEL_GPS167PCI, BUILTIN_FEAT_GPS167PCI }, \ - { GPS_MODEL_GPS163, BUILTIN_FEAT_GPS163 }, \ - { GPS_MODEL_GPS168PCI, BUILTIN_FEAT_GPS168PCI }, \ - { GPS_MODEL_GPS161, BUILTIN_FEAT_GPS161 }, \ - { GPS_MODEL_GPS169PCI, BUILTIN_FEAT_GPS169PCI }, \ - { GPS_MODEL_TCR167PCI, BUILTIN_FEAT_TCR167PCI }, \ - { GPS_MODEL_GPS164, BUILTIN_FEAT_GPS164 }, \ - { GPS_MODEL_GPS170PCI, BUILTIN_FEAT_GPS170PCI }, \ - { GPS_MODEL_PZF511, BUILTIN_FEAT_PZF511 }, \ - { GPS_MODEL_GPS170, BUILTIN_FEAT_GPS170 }, \ - { GPS_MODEL_TCR511, BUILTIN_FEAT_TCR511 }, \ - { GPS_MODEL_AM511, BUILTIN_FEAT_AM511 }, \ - { GPS_MODEL_MSF511, BUILTIN_FEAT_MSF511 }, \ - { GPS_MODEL_GRC170, BUILTIN_FEAT_GRC170 }, \ - { GPS_MODEL_GPS170PEX, BUILTIN_FEAT_GPS170PEX }, \ - { GPS_MODEL_GPS162, BUILTIN_FEAT_GPS162 }, \ - { GPS_MODEL_PTP270PEX, BUILTIN_FEAT_PTP270PEX }, \ - { GPS_MODEL_FRC511PEX, BUILTIN_FEAT_FRC511PEX }, \ - { GPS_MODEL_GEN170, BUILTIN_FEAT_GEN170 }, \ - { GPS_MODEL_TCR170PEX, BUILTIN_FEAT_TCR170PEX }, \ - { GPS_MODEL_WWVB511, BUILTIN_FEAT_WWVB511 }, \ - { GPS_MODEL_MGR170, BUILTIN_FEAT_MGR170 }, \ - { GPS_MODEL_JJY511, BUILTIN_FEAT_JJY511 }, \ - { GPS_MODEL_PZF600, BUILTIN_FEAT_PZF600 }, \ - { GPS_MODEL_TCR600, BUILTIN_FEAT_TCR600 }, \ - { GPS_MODEL_GPS180, BUILTIN_FEAT_GPS180 }, \ - { GPS_MODEL_GLN170, BUILTIN_FEAT_GLN170 }, \ - { GPS_MODEL_GPS180PEX, BUILTIN_FEAT_GPS180PEX }, \ - { GPS_MODEL_TCR180PEX, BUILTIN_FEAT_TCR180PEX }, \ - { GPS_MODEL_PZF180PEX, BUILTIN_FEAT_PZF180PEX }, \ - { GPS_MODEL_MGR180, BUILTIN_FEAT_MGR180 }, \ - { GPS_MODEL_MSF600, BUILTIN_FEAT_MSF600 }, \ - { GPS_MODEL_WWVB600, BUILTIN_FEAT_WWVB600 }, \ - { GPS_MODEL_JJY600, BUILTIN_FEAT_JJY600 }, \ - { GPS_MODEL_GPS180HS, BUILTIN_FEAT_GPS180HS }, \ - { GPS_MODEL_GPS180AMC, BUILTIN_FEAT_GPS180AMC }, \ - { GPS_MODEL_ESI180, BUILTIN_FEAT_ESI180 }, \ - { GPS_MODEL_CPE180, BUILTIN_FEAT_CPE180 }, \ - { GPS_MODEL_LNO180, BUILTIN_FEAT_LNO180 }, \ - { GPS_MODEL_GRC180, BUILTIN_FEAT_GRC180 }, \ - { GPS_MODEL_LIU, BUILTIN_FEAT_LIU }, \ - { GPS_MODEL_DCF600HS, BUILTIN_FEAT_DCF600HS }, \ - { GPS_MODEL_DCF600RS, BUILTIN_FEAT_DCF600RS }, \ - { GPS_MODEL_MRI, BUILTIN_FEAT_MRI }, \ - { GPS_MODEL_BPE, BUILTIN_FEAT_BPE }, \ - { GPS_MODEL_GLN180PEX, BUILTIN_FEAT_GLN180PEX }, \ - { GPS_MODEL_N2X, BUILTIN_FEAT_N2X }, \ - { GPS_MODEL_RSC180, BUILTIN_FEAT_RSC180 }, \ - { GPS_MODEL_LNE_GB, BUILTIN_FEAT_LNE_GB }, \ - { GPS_MODEL_PPG180, BUILTIN_FEAT_PPG180 }, \ - { GPS_MODEL_SCG, BUILTIN_FEAT_SCG }, \ - { 0, 0 } \ +#define GPS_MODEL_BUILTIN_FEATURES \ +{ \ + { GPS_MODEL_GPS166, BUILTIN_FEAT_GPS166 }, \ + { GPS_MODEL_GPS167, BUILTIN_FEAT_GPS167 }, \ + { GPS_MODEL_GPS167SV, BUILTIN_FEAT_GPS167SV }, \ + { GPS_MODEL_GPS167PC, BUILTIN_FEAT_GPS167PC }, \ + { GPS_MODEL_GPS167PCI, BUILTIN_FEAT_GPS167PCI }, \ + { GPS_MODEL_GPS163, BUILTIN_FEAT_GPS163 }, \ + { GPS_MODEL_GPS168PCI, BUILTIN_FEAT_GPS168PCI }, \ + { GPS_MODEL_GPS161, BUILTIN_FEAT_GPS161 }, \ + { GPS_MODEL_GPS169PCI, BUILTIN_FEAT_GPS169PCI }, \ + { GPS_MODEL_TCR167PCI, BUILTIN_FEAT_TCR167PCI }, \ + { GPS_MODEL_GPS164, BUILTIN_FEAT_GPS164 }, \ + { GPS_MODEL_GPS170PCI, BUILTIN_FEAT_GPS170PCI }, \ + { GPS_MODEL_PZF511, BUILTIN_FEAT_PZF511 }, \ + { GPS_MODEL_GPS170, BUILTIN_FEAT_GPS170 }, \ + { GPS_MODEL_TCR511, BUILTIN_FEAT_TCR511 }, \ + { GPS_MODEL_AM511, BUILTIN_FEAT_AM511 }, \ + { GPS_MODEL_MSF511, BUILTIN_FEAT_MSF511 }, \ + { GPS_MODEL_GRC170, BUILTIN_FEAT_GRC170 }, \ + { GPS_MODEL_GPS170PEX, BUILTIN_FEAT_GPS170PEX }, \ + { GPS_MODEL_GPS162, BUILTIN_FEAT_GPS162 }, \ + { GPS_MODEL_PTP270PEX, BUILTIN_FEAT_PTP270PEX }, \ + { GPS_MODEL_FRC511PEX, BUILTIN_FEAT_FRC511PEX }, \ + { GPS_MODEL_GEN170, BUILTIN_FEAT_GEN170 }, \ + { GPS_MODEL_TCR170PEX, BUILTIN_FEAT_TCR170PEX }, \ + { GPS_MODEL_WWVB511, BUILTIN_FEAT_WWVB511 }, \ + { GPS_MODEL_MGR170, BUILTIN_FEAT_MGR170 }, \ + { GPS_MODEL_JJY511, BUILTIN_FEAT_JJY511 }, \ + { GPS_MODEL_PZF600, BUILTIN_FEAT_PZF600 }, \ + { GPS_MODEL_TCR600, BUILTIN_FEAT_TCR600 }, \ + { GPS_MODEL_GPS180, BUILTIN_FEAT_GPS180 }, \ + { GPS_MODEL_GLN170, BUILTIN_FEAT_GLN170 }, \ + { GPS_MODEL_GPS180PEX, BUILTIN_FEAT_GPS180PEX }, \ + { GPS_MODEL_TCR180PEX, BUILTIN_FEAT_TCR180PEX }, \ + { GPS_MODEL_PZF180PEX, BUILTIN_FEAT_PZF180PEX }, \ + { GPS_MODEL_MGR180, BUILTIN_FEAT_MGR180 }, \ + { GPS_MODEL_MSF600, BUILTIN_FEAT_MSF600 }, \ + { GPS_MODEL_WWVB600, BUILTIN_FEAT_WWVB600 }, \ + { GPS_MODEL_JJY600, BUILTIN_FEAT_JJY600 }, \ + { GPS_MODEL_GPS180HS, BUILTIN_FEAT_GPS180HS }, \ + { GPS_MODEL_GPS180AMC, BUILTIN_FEAT_GPS180AMC }, \ + { GPS_MODEL_ESI180, BUILTIN_FEAT_ESI180 }, \ + { GPS_MODEL_CPE180, BUILTIN_FEAT_CPE180 }, \ + { GPS_MODEL_LNO180, BUILTIN_FEAT_LNO180 }, \ + { GPS_MODEL_GRC180, BUILTIN_FEAT_GRC180 }, \ + { GPS_MODEL_LIU, BUILTIN_FEAT_LIU }, \ + { GPS_MODEL_DCF600HS, BUILTIN_FEAT_DCF600HS }, \ + { GPS_MODEL_DCF600RS, BUILTIN_FEAT_DCF600RS }, \ + { GPS_MODEL_MRI, BUILTIN_FEAT_MRI }, \ + { GPS_MODEL_BPE, BUILTIN_FEAT_BPE }, \ + { GPS_MODEL_GLN180PEX, BUILTIN_FEAT_GLN180PEX }, \ + { GPS_MODEL_N2X, BUILTIN_FEAT_N2X }, \ + { GPS_MODEL_RSC180, BUILTIN_FEAT_RSC180 }, \ + { GPS_MODEL_LNE_GB, BUILTIN_FEAT_LNE_GB }, \ + { GPS_MODEL_PPG180, BUILTIN_FEAT_PPG180 }, \ + { GPS_MODEL_SCG, BUILTIN_FEAT_SCG }, \ + { GPS_MODEL_MDU300, BUILTIN_FEAT_MDU300 }, \ + { GPS_MODEL_SDI, BUILTIN_FEAT_SDI }, \ + { GPS_MODEL_FDM180, BUILTIN_FEAT_FDM180 }, \ + { GPS_MODEL_SPT, BUILTIN_FEAT_SPT }, \ + { GPS_MODEL_PZF180, BUILTIN_FEAT_PZF180 }, \ + { GPS_MODEL_REL1000, BUILTIN_FEAT_REL1000 }, \ + { GPS_MODEL_HPS100, BUILTIN_FEAT_HPS100 }, \ + { GPS_MODEL_VSG180, BUILTIN_FEAT_VSG180 }, \ + { GPS_MODEL_MSF180, BUILTIN_FEAT_MSF180 }, \ + { GPS_MODEL_WWVB180, BUILTIN_FEAT_WWVB180 }, \ + { GPS_MODEL_CPC180, BUILTIN_FEAT_CPC180 }, \ + { GPS_MODEL_CTC100, BUILTIN_FEAT_CTC100 }, \ + { GPS_MODEL_TCR180, BUILTIN_FEAT_TCR180 }, \ + { GPS_MODEL_LUE180, BUILTIN_FEAT_LUE180 }, \ + { GPS_MODEL_CPC_01, BUILTIN_FEAT_CPC_01 }, \ + { GPS_MODEL_TSU_01, BUILTIN_FEAT_TSU_01 }, \ + { GPS_MODEL_CMC_01, BUILTIN_FEAT_CMC_01 }, \ + { GPS_MODEL_SCU_01, BUILTIN_FEAT_SCU_01 }, \ + { GPS_MODEL_FCU_01, BUILTIN_FEAT_FCU_01 }, \ + { GPS_MODEL_MSSB100, BUILTIN_FEAT_MSSB100 }, \ + { GPS_MODEL_LNE180SFP, BUILTIN_FEAT_LNE180SFP }, \ + { GPS_MODEL_GTS180, BUILTIN_FEAT_GTS180 }, \ + { GPS_MODEL_GPS180CSM, BUILTIN_FEAT_GPS180CSM }, \ + { GPS_MODEL_GRC181, BUILTIN_FEAT_GRC181 }, \ + { GPS_MODEL_N2X180, BUILTIN_FEAT_N2X180 }, \ + { GPS_MODEL_GNS181PEX, BUILTIN_FEAT_GNS181PEX }, \ + { GPS_MODEL_MDU180, BUILTIN_FEAT_MDU180 }, \ + { GPS_MODEL_MDU312, BUILTIN_FEAT_MDU312 }, \ + { GPS_MODEL_GPS165, BUILTIN_FEAT_GPS165 }, \ + { GPS_MODEL_GNS181_UC, BUILTIN_FEAT_GNS181_UC }, \ + { GPS_MODEL_PSX_4GE, BUILTIN_FEAT_PSX_4GE }, \ + { GPS_MODEL_RSC180RDU, BUILTIN_FEAT_RSC180RDU }, \ + { GPS_MODEL_CPC200, BUILTIN_FEAT_CPC200 }, \ + { GPS_MODEL_FDM180M, BUILTIN_FEAT_FDM180M }, \ + { GPS_MODEL_LSG180, BUILTIN_FEAT_LSG180 }, \ + { GPS_MODEL_GPS190, BUILTIN_FEAT_GPS190 }, \ + { GPS_MODEL_GNS181, BUILTIN_FEAT_GNS181 }, \ + { GPS_MODEL_PIO180, BUILTIN_FEAT_PIO180 }, \ + { GPS_MODEL_FCM180, BUILTIN_FEAT_FCM180 }, \ + { GPS_MODEL_TCR180USB, BUILTIN_FEAT_TCR180USB }, \ + { GPS_MODEL_SSP100, BUILTIN_FEAT_SSP100 }, \ + { GPS_MODEL_GNS165, BUILTIN_FEAT_GNS165 }, \ + { GPS_MODEL_RSC180RDMP, BUILTIN_FEAT_RSC180RDMP }, \ + { GPS_MODEL_GPS16X, BUILTIN_FEAT_GPS16X }, \ + { GPS_MODEL_MSHPS100, BUILTIN_FEAT_MSHPS100 }, \ + { GPS_MODEL_BPE_STM, BUILTIN_FEAT_BPE_STM }, \ + { GPS_MODEL_VSI180, BUILTIN_FEAT_VSI180 }, \ + { GPS_MODEL_GNM181, BUILTIN_FEAT_GNM181 }, \ + { GPS_MODEL_RSCRDU_TTL, BUILTIN_FEAT_RSCRDU_TTL }, \ + { GPS_MODEL_RSC2000, BUILTIN_FEAT_RSC2000 }, \ + { GPS_MODEL_FCU200, BUILTIN_FEAT_FCU200 }, \ + { GPS_MODEL_REL1000_RC, BUILTIN_FEAT_REL1000_RC }, \ + { 0, 0 } \ } + + +/** + * @brief Enumeration of CPU types used in Meinberg products. + * + * @see @ref group_dev_cpu_type_names + * @see ::MBG_DEV_CPU_TYPE_NAMES + */ +enum MBG_DEV_CPU_TYPES +{ + MBG_DEV_CPU_TYPE_UNSPEC, ///< Unspecified, unknown, or special (e.g. embedded system) + MBG_DEV_CPU_TYPE_C509, + MBG_DEV_CPU_TYPE_C166_C167, + MBG_DEV_CPU_TYPE_C163, + MBG_DEV_CPU_TYPE_GP4020, + MBG_DEV_CPU_TYPE_XC164_XC167, + MBG_DEV_CPU_TYPE_T89C5XACX, + MBG_DEV_CPU_TYPE_XE167, + MBG_DEV_CPU_TYPE_SAM3U, + MBG_DEV_CPU_TYPE_SAM3S, + MBG_DEV_CPU_TYPE_STM32F0, + MBG_DEV_CPU_TYPE_STM32F4, + MBG_DEV_CPU_TYPE_STM32F7, + N_MBG_DEV_CPU_TYPES +}; + + + +/** + * @defgroup group_dev_cpu_type_names Name strings of CPU types used with Meinberg devices. + * + * Name strings for the CPU types enumerated in ::MBG_DEV_CPU_TYPES. + * + * @see ::MBG_DEV_CPU_TYPES + * @see ::MBG_DEV_CPU_TYPE_NAMES + * + * @{ */ + +#define MBG_DEV_CPU_NAME_UNSPEC "(unspecified)" +#define MBG_DEV_CPU_NAME_C509 "C509" +#define MBG_DEV_CPU_NAME_C166_C167 "C166/C167" +#define MBG_DEV_CPU_NAME_C163 "C163" +#define MBG_DEV_CPU_NAME_GP4020 "GP4020" +#define MBG_DEV_CPU_NAME_XC164_XC167 "XC164/XC167" +#define MBG_DEV_CPU_NAME_T89C5XACX "T89C5xACx" +#define MBG_DEV_CPU_NAME_XE167 "XE167" +#define MBG_DEV_CPU_NAME_SAM3U "SAM3U" +#define MBG_DEV_CPU_NAME_SAM3S "SAM3S" +#define MBG_DEV_CPU_NAME_STM32F0 "STM32F0" +#define MBG_DEV_CPU_NAME_STM32F4 "STM32F4" +#define MBG_DEV_CPU_NAME_STM32F7 "STM32F7" + +/** @} defgroup group_dev_cpu_type_names */ + + + +/** + * @brief Initializer for an array of CPU type name strings + * + * The array should have ::N_MBG_DEV_CPU_TYPES entries. + * + * @see ::MBG_DEV_CPU_TYPES + * @see @ref MBG_DEV_CPU_TYPE_NAMES + */ +#define MBG_DEV_CPU_TYPE_NAMES \ +{ \ + MBG_DEV_CPU_NAME_UNSPEC, \ + MBG_DEV_CPU_NAME_C509, \ + MBG_DEV_CPU_NAME_C166_C167, \ + MBG_DEV_CPU_NAME_C163, \ + MBG_DEV_CPU_NAME_GP4020, \ + MBG_DEV_CPU_NAME_XC164_XC167, \ + MBG_DEV_CPU_NAME_T89C5XACX, \ + MBG_DEV_CPU_NAME_XE167, \ + MBG_DEV_CPU_NAME_SAM3U, \ + MBG_DEV_CPU_NAME_SAM3S, \ + MBG_DEV_CPU_NAME_STM32F0 \ + MBG_DEV_CPU_NAME_STM32F4 \ + MBG_DEV_CPU_NAME_STM32F7 \ +} + + + +/** + * @brief Initializer for a table of CPU type per device. + * + * Last entry is all zero to indicated end of table. + * + * @see ::GPS_MODEL_CODES + * @see ::MBG_DEV_CPU_TYPES + */ +#define MBG_DEV_CPU_TYPE_TABLE_INIT \ +{ \ + { GPS_MODEL_GPS166, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS167, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS167SV, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS167PC, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS167PCI, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS163, MBG_DEV_CPU_TYPE_C163 }, \ + { GPS_MODEL_GPS168PCI, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS161, MBG_DEV_CPU_TYPE_GP4020 }, \ + { GPS_MODEL_GPS169PCI, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_TCR167PCI, MBG_DEV_CPU_TYPE_C166_C167 }, \ + { GPS_MODEL_GPS164, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_GPS170PCI, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_PZF511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_GPS170, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_TCR511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_AM511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_MSF511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_GRC170, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_GPS170PEX, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_GPS162, MBG_DEV_CPU_TYPE_XE167 }, \ + { GPS_MODEL_PTP270PEX, 0 /* Toradex */ }, \ + { GPS_MODEL_FRC511PEX, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_GEN170, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_TCR170PEX, MBG_DEV_CPU_TYPE_XE167 }, \ + { GPS_MODEL_WWVB511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_MGR170, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_JJY511, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_PZF600, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_TCR600, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GPS180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GLN170, MBG_DEV_CPU_TYPE_XC164_XC167 }, \ + { GPS_MODEL_GPS180PEX, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_TCR180PEX, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_PZF180PEX, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_MGR180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_MSF600, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_WWVB600, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_JJY600, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GPS180HS, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GPS180AMC, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_ESI180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_CPE180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_LNO180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_GRC180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_LIU, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_DCF600HS, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_DCF600RS, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_MRI, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_BPE, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_GLN180PEX, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_N2X, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_RSC180, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_LNE_GB, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_PPG180, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_SCG, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_MDU300, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_SDI, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_FDM180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_SPT, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_PZF180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_REL1000, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_HPS100, 0 }, \ + { GPS_MODEL_VSG180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_MSF180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_WWVB180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_CPC180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_CTC100, 0 }, \ + { GPS_MODEL_TCR180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_LUE180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_CPC_01, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_TSU_01, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_CMC_01, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_SCU_01, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_FCU_01, MBG_DEV_CPU_TYPE_T89C5XACX }, \ + { GPS_MODEL_MSSB100, 0 }, \ + { GPS_MODEL_LNE180SFP, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_GTS180, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_GPS180CSM, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GRC181, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_N2X180, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_GNS181PEX, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_MDU180, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_MDU312, MBG_DEV_CPU_TYPE_SAM3S }, \ + { GPS_MODEL_GPS165, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GNS181_UC, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_PSX_4GE, 0 }, \ + { GPS_MODEL_RSC180RDU, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_CPC200, MBG_DEV_CPU_TYPE_STM32F0 }, \ + { GPS_MODEL_FDM180M, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_LSG180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GPS190, MBG_DEV_CPU_TYPE_STM32F7 }, \ + { GPS_MODEL_GNS181, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_PIO180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_FCM180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_TCR180USB, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_SSP100, 0 }, \ + { GPS_MODEL_GNS165, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_RSC180RDMP, MBG_DEV_CPU_TYPE_STM32F4 }, \ + { GPS_MODEL_GPS16X, MBG_DEV_CPU_TYPE_UNSPEC }, \ + { GPS_MODEL_MSHPS100, 0 }, \ + { GPS_MODEL_BPE_STM, MBG_DEV_CPU_TYPE_STM32F0 }, \ + { GPS_MODEL_VSI180, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_GNM181, MBG_DEV_CPU_TYPE_SAM3U }, \ + { GPS_MODEL_RSCRDU_TTL, 0 }, \ + { GPS_MODEL_RSC2000, 0 }, \ + { GPS_MODEL_FCU200, 0 }, \ + { GPS_MODEL_REL1000_RC, 0 }, \ + { 0, 0 } \ +} + +#endif // !defined( MBG_TGT_DOS ) + /** @} anchor GPS_BUILTIN_FEATURE_DEFS */ +/** + * @brief Initialize a ::RECEIVER_INFO structure for legacy DCF77 receivers + * + * Legacy DCF77 receivers may not provide a ::RECEIVER_INFO structure, + * but have well-known properties which can be used to set up a + * default ::RECEIVER_INFO. + * + * @param[in,out] _p Pointer to a ::RECEIVER_INFO STRUCTURE to be set up + * @param[in] _pdev Pointer to a ::PCPS_DEV structure read before + * + * @see ::_setup_default_receiver_info_gps + */ +#define _setup_default_receiver_info_dcf( _p, _pdev ) \ +do \ +{ \ + memset( (_p), 0, sizeof( *(_p) ) ); \ + \ + (_p)->ticks_per_sec = DEFAULT_GPS_TICKS_PER_SEC; \ + (_p)->n_ucaps = 0; \ + (_p)->n_com_ports = _pcps_has_serial( _pdev ) ? 1 : 0; \ + (_p)->n_str_type = ( (_p)->n_com_ports != 0 ) ? \ + DEFAULT_N_STR_TYPE_DCF : 0; \ +} while ( 0 ) + + + +/** + * @brief Initialize a ::RECEIVER_INFO structure for legacy GPS receivers + * + * Legacy GPS receivers may not provide a ::RECEIVER_INFO structure, + * but have well-known properties which can be used to set up a + * default ::RECEIVER_INFO. + * + * @param[in,out] _p Pointer to a ::RECEIVER_INFO STRUCTURE to be set up + * + * @see ::_setup_default_receiver_info_dcf + */ +#define _setup_default_receiver_info_gps( _p ) \ +do \ +{ \ + memset( (_p), 0, sizeof( *(_p) ) ); \ + \ + (_p)->ticks_per_sec = DEFAULT_GPS_TICKS_PER_SEC; \ + (_p)->n_ucaps = 2; \ + (_p)->n_com_ports = DEFAULT_N_COM; \ + (_p)->n_str_type = DEFAULT_N_STR_TYPE_GPS; \ +} while ( 0 ) + + + /* * The macros below can be used to classify a receiver, * e.g. depending on the time source and/or depending on @@ -1530,9 +2466,20 @@ enum GPS_OSC_TYPES /** - * @brief Enumeration of device features flags reported in ::RECEIVER_INFO::features + * @brief Enumeration of device features flags reported in ::RI_FEATURES * - * Each flags indicates if a device supports the associated feature. + * Used with ::RECEIVER_INFO::features. Each flags indicates if a device + * supports the associated feature, but due to the limited bit size of + * the ::RI_FEATURES type the number of these features is limited to 32. + * + * To extend the number of possible features the ::MBG_XFEATURE_BITS, the + * ::MBG_XFEATURE_BUFFER structure and associated definitions have been + * introduced, which are supported by devices which have ::GPS_HAS_XFEATURE + * set in ::RI_FEATURES. + * + * @see ::RI_FEATURES + * @see ::MBG_XFEATURE_BITS + * @see ::MBG_XFEATURE_BUFFER */ enum GPS_FEATURE_BITS { @@ -1569,12 +2516,12 @@ enum GPS_FEATURE_BITS GPS_FEAT_NET_CFG, ///< supports extended network interface configuration, supersedes ::GPS_FEAT_LAN_IP4 GPS_FEAT_VST, ///< supports VST (Versatile Storage) API and structures GPS_FEAT_SHS, ///< supports SHS (Secure Hybrid System) API and structures + GPS_FEAT_XBP, ///< supports XBP (eXtended Binary Protocol) API and structures, see @ref group_xbp + GPS_FEAT_XFEATURE, ///< support eXtended features, see @ref group_xfeature + N_GPS_FEATURE ///< the number of known ::GPS_FEATURE_BITS, should now be at its limit, i.e. 32. - N_GPS_FEATURE ///< the number of valid features - /* - * If new features are added then care must be taken to update the associated - * definitions below accordingly, e.g. string initializers and bit masks. - */ + // WARNING: There are no more unassigned feature bits available here. + // New features have to be defined using the ::MBG_XFEATURE_BITS }; @@ -1614,7 +2561,9 @@ enum GPS_FEATURE_BITS "NTP", \ "Ext. Network Config", \ "Versatile Storage", \ - "SHS" \ + "SHS", \ + "Extended Binary Protocol", \ + "Extended Features" \ } @@ -1625,40 +2574,41 @@ enum GPS_FEATURE_BITS * * @anchor GPS_FEATURE_MASKS @{ */ -#define GPS_HAS_PPS ( 1UL << GPS_FEAT_PPS ) ///< see ::GPS_FEAT_PPS -#define GPS_HAS_PPM ( 1UL << GPS_FEAT_PPM ) ///< see ::GPS_FEAT_PPM -#define GPS_HAS_SYNTH ( 1UL << GPS_FEAT_SYNTH ) ///< see ::GPS_FEAT_SYNTH -#define GPS_HAS_DCFMARKS ( 1UL << GPS_FEAT_DCFMARKS ) ///< see ::GPS_FEAT_DCFMARKS -#define GPS_HAS_IRIG_TX ( 1UL << GPS_FEAT_IRIG_TX ) ///< see ::GPS_FEAT_IRIG_TX -#define GPS_HAS_IRIG_RX ( 1UL << GPS_FEAT_IRIG_RX ) ///< see ::GPS_FEAT_IRIG_RX -#define GPS_HAS_LAN_IP4 ( 1UL << GPS_FEAT_LAN_IP4 ) ///< see ::GPS_FEAT_LAN_IP4 -#define GPS_HAS_MULTI_REF ( 1UL << GPS_FEAT_MULTI_REF ) ///< see ::GPS_FEAT_MULTI_REF - -#define GPS_HAS_RCV_TIMEOUT ( 1UL << GPS_FEAT_RCV_TIMEOUT ) ///< see ::GPS_FEAT_RCV_TIMEOUT -#define GPS_HAS_IGNORE_LOCK ( 1UL << GPS_FEAT_IGNORE_LOCK ) ///< see ::GPS_FEAT_IGNORE_LOCK -#define GPS_HAS_5_MHZ ( 1UL << GPS_FEAT_5_MHZ ) ///< see ::GPS_FEAT_5_MHZ -#define GPS_HAS_XMULTI_REF ( 1UL << GPS_FEAT_XMULTI_REF ) ///< see ::GPS_FEAT_XMULTI_REF -#define GPS_HAS_OPT_SETTINGS ( 1UL << GPS_FEAT_OPT_SETTINGS ) ///< see ::GPS_FEAT_OPT_SETTINGS -#define GPS_HAS_TIME_SCALE ( 1UL << GPS_FEAT_TIME_SCALE ) ///< see ::GPS_FEAT_TIME_SCALE -#define GPS_HAS_IRIG_CTRL_BITS ( 1UL << GPS_FEAT_IRIG_CTRL_BITS ) ///< see ::GPS_FEAT_IRIG_CTRL_BITS -#define GPS_HAS_PTP ( 1UL << GPS_FEAT_PTP ) ///< see ::GPS_FEAT_PTP - -#define GPS_HAS_NAV_ENGINE_SETTINGS ( 1UL << GPS_FEAT_NAV_ENGINE_SETTINGS ) ///< see ::GPS_FEAT_NAV_ENGINE_SETTINGS -#define GPS_HAS_RAW_IRIG_DATA ( 1UL << GPS_FEAT_RAW_IRIG_DATA ) ///< see ::GPS_FEAT_RAW_IRIG_DATA -#define GPS_HAS_RAW_IRIG_TIME ( 1UL << GPS_FEAT_RAW_IRIG_TIME ) ///< see ::GPS_FEAT_RAW_IRIG_TIME -#define GPS_HAS_PTP_UNICAST ( 1UL << GPS_FEAT_PTP_UNICAST ) ///< see ::GPS_FEAT_PTP_UNICAST -#define GPS_HAS_GPIO ( 1UL << GPS_FEAT_GPIO ) ///< see ::GPS_FEAT_GPIO -#define GPS_HAS_XMRS_MULT_INSTC ( 1UL << GPS_FEAT_XMRS_MULT_INSTC ) ///< see ::GPS_FEAT_XMRS_MULT_INSTC -#define GPS_HAS_10MHZ_DISBD ( 1UL << GPS_FEAT_10MHZ_DISBD ) ///< see ::GPS_FEAT_10MHZ_DISBD -#define GPS_HAS_EVT_LOG ( 1UL << GPS_FEAT_EVT_LOG ) ///< see ::GPS_FEAT_EVT_LOG - -#define GPS_HAS_IMS ( 1UL << GPS_FEAT_IMS ) ///< see ::GPS_FEAT_IMS -#define GPS_HAS_HAVEQUICK ( 1UL << GPS_FEAT_HAVEQUICK ) ///< see ::GPS_FEAT_HAVEQUICK -#define GPS_HAS_NTP ( 1UL << GPS_FEAT_NTP ) ///< see ::GPS_FEAT_NTP -#define GPS_HAS_NET_CFG ( 1UL << GPS_FEAT_NET_CFG ) ///< see ::GPS_FEAT_NET_CFG -#define GPS_HAS_VST ( 1UL << GPS_FEAT_VST ) ///< see ::GPS_FEAT_VST -#define GPS_HAS_SHS ( 1UL << GPS_FEAT_SHS ) ///< see ::GPS_FEAT_SHS - +#define GPS_HAS_PPS ( 1UL << GPS_FEAT_PPS ) ///< See ::GPS_FEAT_PPS +#define GPS_HAS_PPM ( 1UL << GPS_FEAT_PPM ) ///< See ::GPS_FEAT_PPM +#define GPS_HAS_SYNTH ( 1UL << GPS_FEAT_SYNTH ) ///< See ::GPS_FEAT_SYNTH +#define GPS_HAS_DCFMARKS ( 1UL << GPS_FEAT_DCFMARKS ) ///< See ::GPS_FEAT_DCFMARKS +#define GPS_HAS_IRIG_TX ( 1UL << GPS_FEAT_IRIG_TX ) ///< See ::GPS_FEAT_IRIG_TX +#define GPS_HAS_IRIG_RX ( 1UL << GPS_FEAT_IRIG_RX ) ///< See ::GPS_FEAT_IRIG_RX +#define GPS_HAS_LAN_IP4 ( 1UL << GPS_FEAT_LAN_IP4 ) ///< See ::GPS_FEAT_LAN_IP4 +#define GPS_HAS_MULTI_REF ( 1UL << GPS_FEAT_MULTI_REF ) ///< See ::GPS_FEAT_MULTI_REF + +#define GPS_HAS_RCV_TIMEOUT ( 1UL << GPS_FEAT_RCV_TIMEOUT ) ///< See ::GPS_FEAT_RCV_TIMEOUT +#define GPS_HAS_IGNORE_LOCK ( 1UL << GPS_FEAT_IGNORE_LOCK ) ///< See ::GPS_FEAT_IGNORE_LOCK +#define GPS_HAS_5_MHZ ( 1UL << GPS_FEAT_5_MHZ ) ///< See ::GPS_FEAT_5_MHZ +#define GPS_HAS_XMULTI_REF ( 1UL << GPS_FEAT_XMULTI_REF ) ///< See ::GPS_FEAT_XMULTI_REF +#define GPS_HAS_OPT_SETTINGS ( 1UL << GPS_FEAT_OPT_SETTINGS ) ///< See ::GPS_FEAT_OPT_SETTINGS +#define GPS_HAS_TIME_SCALE ( 1UL << GPS_FEAT_TIME_SCALE ) ///< See ::GPS_FEAT_TIME_SCALE +#define GPS_HAS_IRIG_CTRL_BITS ( 1UL << GPS_FEAT_IRIG_CTRL_BITS ) ///< See ::GPS_FEAT_IRIG_CTRL_BITS +#define GPS_HAS_PTP ( 1UL << GPS_FEAT_PTP ) ///< See ::GPS_FEAT_PTP + +#define GPS_HAS_NAV_ENGINE_SETTINGS ( 1UL << GPS_FEAT_NAV_ENGINE_SETTINGS ) ///< See ::GPS_FEAT_NAV_ENGINE_SETTINGS +#define GPS_HAS_RAW_IRIG_DATA ( 1UL << GPS_FEAT_RAW_IRIG_DATA ) ///< See ::GPS_FEAT_RAW_IRIG_DATA +#define GPS_HAS_RAW_IRIG_TIME ( 1UL << GPS_FEAT_RAW_IRIG_TIME ) ///< See ::GPS_FEAT_RAW_IRIG_TIME +#define GPS_HAS_PTP_UNICAST ( 1UL << GPS_FEAT_PTP_UNICAST ) ///< See ::GPS_FEAT_PTP_UNICAST +#define GPS_HAS_GPIO ( 1UL << GPS_FEAT_GPIO ) ///< See ::GPS_FEAT_GPIO +#define GPS_HAS_XMRS_MULT_INSTC ( 1UL << GPS_FEAT_XMRS_MULT_INSTC ) ///< See ::GPS_FEAT_XMRS_MULT_INSTC +#define GPS_HAS_10MHZ_DISBD ( 1UL << GPS_FEAT_10MHZ_DISBD ) ///< See ::GPS_FEAT_10MHZ_DISBD +#define GPS_HAS_EVT_LOG ( 1UL << GPS_FEAT_EVT_LOG ) ///< See ::GPS_FEAT_EVT_LOG + +#define GPS_HAS_IMS ( 1UL << GPS_FEAT_IMS ) ///< See ::GPS_FEAT_IMS +#define GPS_HAS_HAVEQUICK ( 1UL << GPS_FEAT_HAVEQUICK ) ///< See ::GPS_FEAT_HAVEQUICK +#define GPS_HAS_NTP ( 1UL << GPS_FEAT_NTP ) ///< See ::GPS_FEAT_NTP +#define GPS_HAS_NET_CFG ( 1UL << GPS_FEAT_NET_CFG ) ///< See ::GPS_FEAT_NET_CFG +#define GPS_HAS_VST ( 1UL << GPS_FEAT_VST ) ///< See ::GPS_FEAT_VST +#define GPS_HAS_SHS ( 1UL << GPS_FEAT_SHS ) ///< See ::GPS_FEAT_SHS +#define GPS_HAS_XBP ( 1UL << GPS_FEAT_XBP ) ///< See ::GPS_FEAT_XBP +#define GPS_HAS_XFEATURE ( 1UL << GPS_FEAT_XFEATURE ) ///< See ::GPS_FEAT_XFEATURE // the next ones are special since they just shadow another flag: #define GPS_HAS_REF_OFFS GPS_HAS_IRIG_RX ///< always supported with IRIG inputs, see ::GPS_HAS_IRIG_RX @@ -1667,6 +2617,157 @@ enum GPS_FEATURE_BITS /** @} anchor GPS_FEATURE_MASKS */ +/** + * @defgroup group_xfeature Extended feature definitions + * + * @note These structures and definitions are only supported by a device + * if ::GPS_HAS_XFEATURE is set in ::RECEIVER_INFO::features. + * + * @{ */ + + +/** + * @brief The maximum number of feature bits supported by the MBG_XFEATURE API. + * + * Warning: Changing this number breaks API compatibility! + * + * @see ::MBG_XFEATURE_BITS + */ +#define MAX_XFEATURE_BITS 1024 + + + +/** + * @brief Enumeration of defined extended features. + * + * @see ::MBG_XFEATURE_NAMES + * @see ::MBG_XFEATURE_BUFFER + */ +enum MBG_XFEATURE_BITS +{ + MBG_XFEATURE_TLV_API, ///< Supports generic TLV API, see @ref group_tlv_api + MBG_XFEATURE_SAVE_CFG, ///< Supports the ::GPS_SAVE_CFG command + MBG_XFEATURE_LED_API, ///< Supports programmable LED API, see @ref group_led_api + MBG_XFEATURE_LNE_API, ///< Supports specific LNE API, see @ref group_lne_api + MBG_XFEATURE_PWR_CTL_API, ///< Supports power control, see @ref group_pwr_ctl_api + MBG_XFEATURE_EXT_SYS_INFO, ///< Supports extended revision information, see @ref group_ext_sys_info + MBG_XFEATURE_TRANSACTIONS, ///< Supports the ::GPS_BEGIN_TRANSACTION and ::GPS_END_TRANSACTION commands, see also ::MBG_TRANSACTION_TYPES + MBG_XFEATURE_REBOOT, ///< Supports the ::GPS_REBOOT command + MBG_XFEATURE_CLK_RES_INFO, ///< Supports the ::GPS_CLK_RES_INFO command, see @ref group_clk_res_info + MBG_XFEATURE_UCAP_NET, ///< Supports the ::GPS_UCAP_NET_GLB_INFO and ::GPS_UCAP_NET_RECV_INFO_IDX commands, see @ref group_ucap_net + MBG_XFEATURE_REQ_TTM, ///< Supports requesting ::TTM via the ::GPS_TIME command + MBG_XFEATURE_IO_PORTS, ///< Supports I/O port structures, see @ref group_io_ports + MBG_XFEATURE_MONITORING, ///< Supports monitoring / notifications, see @ref group_monitoring + MBG_XFEATURE_XHE, ///< Supports XHE external rubidium unit I/O commands + MBG_XFEATURE_TAINTED_CFG, ///< Supports tainted config structures, see @ref group_tainted_cfg + MBG_XFEATURE_PUSH_MSGS, ///< Supports commands ::GPS_REGISTER_PUSH_MSGS and ::GPS_UNREGISTER_PUSH_MSGS + MBG_XFEATURE_USER_AUTH, ///< Supports user authentication and command ::GPS_AUTH_USER_INFO + MBG_XFEATURE_USER_MNGMNT, ///< Supports user management, see @ref group_user_mngmnt + MBG_XFEATURE_SERVICE, ///< Supports service management, see @ref group_service_mngmnt + MBG_XFEATURE_UP_CONV, ///< Instead of a standard L1 antenna, a Meinberg antenna/converter can be used with this GNSS device. + MBG_XFEATURE_FW_MNGMNT, ///< Supports firmware management, see @ref group_fw_mngmnt + MBG_XFEATURE_DAC_CTRL_PCI, ///< Supports DAC control via PCI or USB bus API. + MBG_XFEATURE_DATABASE, ///< Supports database(s), see @ref group_database + MBG_XFEATURE_GNSS_MODE, ///< Supports GPS_GNSS_MODE + MBG_XFEATURE_PTP_NG, ///< Supports PTP next gen API, see @ref group_ptp_ng + MBG_XFEATURE_SYS_REF, ///< Supports new system reference API, see @ref group_sys_ref + MBG_XFEATURE_FCU_API, ///< Supports FCU features, see @ref group_fcu_api + N_MBG_XFEATURE ///< Number of defined extended features + // NOTE If new features are appended here then an appropriate feature + // name string has to be appended to ::MBG_XFEATURE_NAMES, and care must + // be taken that ::N_MBG_XFEATURE doesn't exceed ::MAX_XFEATURE_BITS. +}; + + + +/** + * @brief Names of extended device features + * + * Can be used to initialize a string array of ::N_MBG_XFEATURE entries, + * so the number of strings must correspond to ::N_MBG_XFEATURE. + * + * @see ::MBG_XFEATURE_BITS + */ +#define MBG_XFEATURE_NAMES \ +{ \ + "Generic TLV API", \ + "Save Config On Card", \ + "Programmable LED API", \ + "LNE API", \ + "Power Control API", \ + "Extended Revision Info", \ + "Transaction commands", \ + "Reboot Command", \ + "Clock Resolution Info", \ + "Extended User Captures", \ + "Request TTM", \ + "I/O Ports", \ + "Monitoring", \ + "XHE Unit", \ + "Tainted Config", \ + "Push Messages", \ + "User Authentication", \ + "User Management", \ + "Service Management", \ + "Antenna Converter", \ + "Firmware Management", \ + "DAC control via bus", \ + "Database", \ + "GNSS Messages", \ + "PTP Next Gen.", \ + "System Reference" \ +} + + + +/** + * @brief Array size required to store all extended features + * + * The number of bytes required to store up to ::MAX_XFEATURE_BITS + * feature bits in a byte array. + */ +#define MAX_XFEATURE_BYTES ( MAX_XFEATURE_BITS / 8 ) + + + +/** + * @brief A structure used to store extended device features. + * + * Up to ::MAX_XFEATURE_BITS totally can be stored, but only + * ::N_MBG_XFEATURE extended features are currently defined. + * The ::_set_xfeature_bit macro should be used by the firmware + * to set a feature bit in the buffer, and the ::check_xfeature + * function should be used to implement API calls which test if an + * extended feature is supported. + * + * @see ::_set_xfeature_bit + * @see ::check_xfeature + */ +typedef struct mbg_xfeature_buffer_s +{ + uint8_t b[MAX_XFEATURE_BYTES]; + +} MBG_XFEATURE_BUFFER; + + + +/** + * @brief Set an extended feature bit in a ::MBG_XFEATURE_BUFFER + * + * Should be used by the firmware only to set one of the ::MBG_XFEATURE_BITS + * in an ::MBG_XFEATURE_BUFFER after power-up. + * + * @param[in] _xf_bit One of the ::MBG_XFEATURE_BITS + * @param[in] _xf_buffp Pointer to an ::MBG_XFEATURE_BUFFER + */ +#define _set_xfeature_bit( _xf_bit, _xf_buffp ) \ + _set_array_bit( _xf_bit, (_xf_buffp)->b, MAX_XFEATURE_BYTES ) + + +/** @} defgroup group_xfeature */ + + + /* * The features below are supported by default by older * C166 based GPS receivers: @@ -1697,9 +2798,9 @@ enum RECEIVER_INFO_FLAG_BITS */ enum RECEIVER_INFO_FLAG_MASKS { - GPS_OSC_CFG_SUPP = ( 1UL << GPS_BIT_OSC_CFG_SUPP ), ///< see ::GPS_BIT_OSC_CFG_SUPP - GPS_IRIG_FO_IN = ( 1UL << GPS_BIT_IRIG_FO_IN ), ///< see ::GPS_BIT_IRIG_FO_IN - GPS_HAS_FPGA = ( 1UL << GPS_BIT_HAS_FPGA ) ///< see ::GPS_BIT_HAS_FPGA + GPS_OSC_CFG_SUPP = ( 1UL << GPS_BIT_OSC_CFG_SUPP ), ///< See ::GPS_BIT_OSC_CFG_SUPP + GPS_IRIG_FO_IN = ( 1UL << GPS_BIT_IRIG_FO_IN ), ///< See ::GPS_BIT_IRIG_FO_IN + GPS_HAS_FPGA = ( 1UL << GPS_BIT_HAS_FPGA ) ///< See ::GPS_BIT_HAS_FPGA }; @@ -1719,11 +2820,7 @@ typedef union { CSUM csum; uint32_t fsize; - #if _IS_MBG_FIRMWARE - uint32_t start_addr; - #else - uint8_t *start_addr; - #endif + uint32_t start_addr; char name[FPGA_NAME_SIZE]; } hdr; @@ -1763,28 +2860,62 @@ typedef struct * GPS time is counted by the week numbers since the epoch, plus second * of the week, plus fraction of the second. The week number transmitted * by the satellites rolls over from 1023 to 0, but Meinberg devices - * just continue to count the weeks beyond the 1024 week limit to keep + * simply continue counting weeks beyond the 1024-week limit to maintain * the receiver's internal time. * * %UTC time differs from GPS time since a number of leap seconds have - * been inserted in the %UTC time scale after the GPS epoche. The number + * been inserted in the %UTC time scale after the GPS epoch. The number * of leap seconds is disseminated by the satellites using the ::UTC * parameter set, which also provides info on pending leap seconds. */ typedef struct { - uint16_t wn; ///< the week number since GPS has been installed - uint32_t sec; ///< the second of that week - uint32_t tick; ///< fractions of a second, 1/::RECEIVER_INFO::ticks_per_sec units + GPS_WNUM wn; ///< The week number since the GPS system has been put into operation. + GPS_WSEC sec; ///< The second of a week. + GPS_TICK tick; ///< Fractions of a second, 1/::RECEIVER_INFO::ticks_per_sec units. } T_GPS; #define _mbg_swab_t_gps( _p ) \ +do \ { \ _mbg_swab16( &(_p)->wn ); \ _mbg_swab32( &(_p)->sec ); \ _mbg_swab32( &(_p)->tick ); \ -} +} while ( 0 ) + + + +/** + * @brief A type of status variable to be used with ::TM_GPS, etc. + * + * @see ::TM_GPS_STATUS_BIT_MASKS + */ +typedef uint16_t TM_GPS_STATUS; + +#define _mbg_swab_tm_gps_status( _p ) _mbg_swab16( _p ) + + + + +/** + * @brief Type of an extended TM status which is mainly used inside the firmware. + * + * @see ::TM_GPS_STATUS_BIT_MASKS + * @see @ref TM_GPS_STATUS_EXT_BIT_MASKS + */ +typedef uint32_t TM_GPS_STATUS_EXT; + +#define _mbg_swab_tm_gps_status_ext( _p ) _mbg_swab32( _p ) + + +/** + * @brief An alias for ::TM_GPS_STATUS_EXT + * + * This has been used in existing source code. + */ +#define TM_STATUS_EXT TM_GPS_STATUS_EXT + /** @@ -1811,19 +2942,20 @@ typedef struct int8_t min; ///< minutes, 0..59 int8_t sec; ///< seconds, 0..59, or 60 in case of inserted leap second int32_t frac; ///< fractions of a second, 1/::RECEIVER_INFO::ticks_per_sec units - int32_t offs_from_utc; ///< local time's offset from %UTC - uint16_t status; ///< status flags, see ::TM_GPS_STATUS_BIT_MASKS + int32_t offs_from_utc; ///< local time offset from %UTC [sec] + TM_GPS_STATUS status; ///< status flags, see ::TM_GPS_STATUS_BIT_MASKS } TM_GPS; -#define _mbg_swab_tm_gps( _p ) \ -{ \ - _mbg_swab16( &(_p)->year ); \ - _mbg_swab16( &(_p)->yday ); \ - _mbg_swab32( &(_p)->frac ); \ - _mbg_swab32( &(_p)->offs_from_utc ); \ - _mbg_swab16( &(_p)->status ); \ -} +#define _mbg_swab_tm_gps( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->year ); \ + _mbg_swab16( &(_p)->yday ); \ + _mbg_swab32( &(_p)->frac ); \ + _mbg_swab32( &(_p)->offs_from_utc ); \ + _mbg_swab_tm_gps_status( &(_p)->status ); \ +} while ( 0 ) /** @@ -1848,9 +2980,9 @@ enum TM_GPS_STATUS_BITS TM_BIT_EXT_SYNC, ///< synchronized externally TM_BIT_HOLDOVER, ///< in holdover mode after previous synchronization TM_BIT_ANT_SHORT, ///< antenna cable short circuited - TM_BIT_NO_WARM, ///< OCXO has not warmed up + TM_BIT_NO_WARM, ///< oscillator control loop not settled TM_BIT_ANT_DISCONN, ///< antenna currently disconnected - TM_BIT_SYN_FLAG, ///< TIME_SYN output is low + TM_BIT_SYN_FLAG, ///< clock not synchronized, reflects the state of the "time sync error" output pin TM_BIT_NO_SYNC, ///< time sync actually not verified TM_BIT_NO_POS ///< position actually not verified, LOCK LED off }; @@ -1866,51 +2998,68 @@ enum TM_GPS_STATUS_BITS */ enum TM_GPS_STATUS_BIT_MASKS { - TM_UTC = ( 1UL << TM_BIT_UTC ), ///< see ::TM_BIT_UTC - TM_LOCAL = ( 1UL << TM_BIT_LOCAL ), ///< see ::TM_BIT_LOCAL - TM_DL_ANN = ( 1UL << TM_BIT_DL_ANN ), ///< see ::TM_BIT_DL_ANN - TM_DL_ENB = ( 1UL << TM_BIT_DL_ENB ), ///< see ::TM_BIT_DL_ENB - TM_LS_ANN = ( 1UL << TM_BIT_LS_ANN ), ///< see ::TM_BIT_LS_ANN - TM_LS_ENB = ( 1UL << TM_BIT_LS_ENB ), ///< see ::TM_BIT_LS_ENB - TM_LS_ANN_NEG = ( 1UL << TM_BIT_LS_ANN_NEG ), ///< see ::TM_BIT_LS_ANN_NEG - TM_INVT = ( 1UL << TM_BIT_INVT ), ///< see ::TM_BIT_INVT - - TM_EXT_SYNC = ( 1UL << TM_BIT_EXT_SYNC ), ///< see ::TM_BIT_EXT_SYNC - TM_HOLDOVER = ( 1UL << TM_BIT_HOLDOVER ), ///< see ::TM_BIT_HOLDOVER - TM_ANT_SHORT = ( 1UL << TM_BIT_ANT_SHORT ), ///< see ::TM_BIT_ANT_SHORT - TM_NO_WARM = ( 1UL << TM_BIT_NO_WARM ), ///< see ::TM_BIT_NO_WARM - TM_ANT_DISCONN = ( 1UL << TM_BIT_ANT_DISCONN ), ///< see ::TM_BIT_ANT_DISCONN - TM_SYN_FLAG = ( 1UL << TM_BIT_SYN_FLAG ), ///< see ::TM_BIT_SYN_FLAG - TM_NO_SYNC = ( 1UL << TM_BIT_NO_SYNC ), ///< see ::TM_BIT_NO_SYNC - TM_NO_POS = ( 1UL << TM_BIT_NO_POS ) ///< see ::TM_BIT_NO_POS + TM_UTC = ( 1UL << TM_BIT_UTC ), ///< See ::TM_BIT_UTC + TM_LOCAL = ( 1UL << TM_BIT_LOCAL ), ///< See ::TM_BIT_LOCAL + TM_DL_ANN = ( 1UL << TM_BIT_DL_ANN ), ///< See ::TM_BIT_DL_ANN + TM_DL_ENB = ( 1UL << TM_BIT_DL_ENB ), ///< See ::TM_BIT_DL_ENB + TM_LS_ANN = ( 1UL << TM_BIT_LS_ANN ), ///< See ::TM_BIT_LS_ANN + TM_LS_ENB = ( 1UL << TM_BIT_LS_ENB ), ///< See ::TM_BIT_LS_ENB + TM_LS_ANN_NEG = ( 1UL << TM_BIT_LS_ANN_NEG ), ///< See ::TM_BIT_LS_ANN_NEG + TM_INVT = ( 1UL << TM_BIT_INVT ), ///< See ::TM_BIT_INVT + + TM_EXT_SYNC = ( 1UL << TM_BIT_EXT_SYNC ), ///< See ::TM_BIT_EXT_SYNC + TM_HOLDOVER = ( 1UL << TM_BIT_HOLDOVER ), ///< See ::TM_BIT_HOLDOVER + TM_ANT_SHORT = ( 1UL << TM_BIT_ANT_SHORT ), ///< See ::TM_BIT_ANT_SHORT + TM_NO_WARM = ( 1UL << TM_BIT_NO_WARM ), ///< See ::TM_BIT_NO_WARM + TM_ANT_DISCONN = ( 1UL << TM_BIT_ANT_DISCONN ), ///< See ::TM_BIT_ANT_DISCONN + TM_SYN_FLAG = ( 1UL << TM_BIT_SYN_FLAG ), ///< See ::TM_BIT_SYN_FLAG + TM_NO_SYNC = ( 1UL << TM_BIT_NO_SYNC ), ///< See ::TM_BIT_NO_SYNC + TM_NO_POS = ( 1UL << TM_BIT_NO_POS ) ///< See ::TM_BIT_NO_POS }; /** - * @brief Type of an extended TM status which is mainly used inside the firmware - */ -typedef uint32_t TM_STATUS_EXT; - -/** - * @brief Enumeration of extended status bits used with ::TM_STATUS_EXT + * @brief Extended status flag bits used to define @ref TM_GPS_STATUS_EXT_BIT_MASKS * * @note The lower 16 bits correspond to ::TM_GPS_STATUS_BITS + * + * @see ::TM_GPS_STATUS_BITS + * @see @ref TM_GPS_STATUS_EXT_BIT_MASKS */ -enum TM_GPS_STATUS_BITS_EX +enum TM_GPS_STATUS_EXT_BITS { TM_BIT_SCALE_GPS = 16, ///< time scale configured to return GPS time TM_BIT_SCALE_TAI ///< time scale configured to return TAI - // the remaining bits are reserved + // The remaining bits are reserved. }; -// The following bits are only used with the ::TM_STATUS_X type: -#define TM_SCALE_GPS ( 1UL << TM_BIT_SCALE_GPS ) -#define TM_SCALE_TAI ( 1UL << TM_BIT_SCALE_TAI ) + +/** + * @brief Bit masks to be only used with ::TM_GPS_STATUS_EXT. + * + * @note The lower 16 bits correspond to ::TM_GPS_STATUS_BIT_MASKS + * + * @see ::TM_GPS_STATUS_EXT + * @see ::TM_GPS_STATUS_BIT_MASKS + * @see ::TM_GPS_STATUS_EXT_BITS + * + * @anchor TM_GPS_STATUS_EXT_BIT_MASKS @{ */ + +#define TM_SCALE_GPS ( 1UL << TM_BIT_SCALE_GPS ) ///< See ::TM_BIT_SCALE_GPS +#define TM_SCALE_TAI ( 1UL << TM_BIT_SCALE_TAI ) ///< See ::TM_BIT_SCALE_TAI + +/** @} anchor TM_GPS_STATUS_EXT_BIT_MASKS */ + + +#define ANN_LIMIT ( - ( SECS_PER_HOUR - SECS_PER_MIN ) ) +#define ANN_LIMIT_DCF ( - ( SECS_PER_HOUR + SECS_PER_MIN ) ) + #define TM_MSK_TIME_VALID ( TM_UTC | TM_SCALE_GPS | TM_SCALE_TAI ) + /** * @brief A structure used to transmit information on date and time * @@ -1928,33 +3077,12 @@ typedef struct } TTM; #define _mbg_swab_ttm( _p ) \ +do \ { \ _mbg_swab16( &(_p)->channel ); \ _mbg_swab_t_gps( &(_p)->t ); \ _mbg_swab_tm_gps( &(_p)->tm ); \ -} - - - -/** - * @brief A timestamp with nanosecond resolution - */ -typedef struct -{ - int32_t nano_secs; ///< [nanoseconds] - int32_t secs; ///< [seconds] - -} NANO_TIME; - -#define _mbg_swab_nano_time( _p ) \ -{ \ - _mbg_swab32( &(_p)->nano_secs ); \ - _mbg_swab32( &(_p)->secs ); \ -} - -// The macro below checks if a ::NANO_TIME value is negative. -#define _nano_time_negative( _nt ) \ - ( ( (_nt)->secs < 0 ) || ( (_nt)->nano_secs < 0 ) ) +} while ( 0 ) @@ -2051,7 +3179,7 @@ typedef struct /* == MAX_SYNTH_FREQ * 10^(MAX_SYNTH_RANGE-1) */ /** - * @brief The synthesizer's phase is only be synchronized if the frequency is below this limit + * @brief The phase of the synthesizer is only synchronized when the frequency is below this limit. */ #define SYNTH_PHASE_SYNC_LIMIT 10000UL ///< 10 kHz @@ -2092,11 +3220,12 @@ typedef struct } SYNTH; #define _mbg_swab_synth( _p ) \ +do \ { \ _mbg_swab16( &(_p)->freq ); \ _mbg_swab16( &(_p)->range ); \ _mbg_swab16( &(_p)->phase ); \ -} +} while ( 0 ) /** @@ -2156,9 +3285,15 @@ typedef char TZ_NAME[6]; /** * @brief Time zone / daylight saving parameters * - * This structure is used to specify how a device is to convert - * on-board %UTC to local time, including computation of beginning - * and end of daylight saving time (DST), if required. + * This structure is used to specify how a device converts on-board %UTC + * to local time, including computation of beginning and end of daylight + * saving time (DST), if required. + * + * @note The ::TZDL structure contains members of type ::TM_GPS to specify + * the times for beginning and end of DST. However, the ::TM_GPS::frac, + * ::TM_GPS::offs_from_utc, and ::TM_GPS::status fields of these ::TZDL::tm_on + * and ::TZDL::tm_off members are ignored for the conversion to local time, + * and thus should be 0. */ typedef struct { @@ -2171,12 +3306,13 @@ typedef struct } TZDL; #define _mbg_swab_tzdl( _p ) \ +do \ { \ _mbg_swab32( &(_p)->offs ); \ _mbg_swab32( &(_p)->offs_dl ); \ _mbg_swab_tm_gps( &(_p)->tm_on ); \ _mbg_swab_tm_gps( &(_p)->tm_off ); \ -} +} while ( 0 ) /** @@ -2191,7 +3327,7 @@ typedef struct // Below there are some initializers for commonly used TZDL configurations: -#define DEFAULT_TZDL_AUTO_YEAR ( 2007 | DL_AUTO_FLAG ) +#define DEFAULT_TZDL_AUTO_YEAR ( (int16_t) ( 2007L | DL_AUTO_FLAG ) ) #define DEFAULt_TZDL_OFFS_DL 3600L ///< usually DST is +1 hour @@ -2329,12 +3465,13 @@ typedef struct } ANT_INFO; #define _mbg_swab_ant_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->status ); \ _mbg_swab_tm_gps( &(_p)->tm_disconn ); \ _mbg_swab_tm_gps( &(_p)->tm_reconn ); \ _mbg_swab32( &(_p)->delta_t ); \ -} +} while ( 0 ) /** @@ -2370,12 +3507,13 @@ typedef struct } ENABLE_FLAGS; #define _mbg_swab_enable_flags( _p ) \ +do \ { \ _mbg_swab16( &(_p)->serial ); \ _mbg_swab16( &(_p)->pulses ); \ _mbg_swab16( &(_p)->freq ); \ _mbg_swab16( &(_p)->synth ); \ -} +} while ( 0 ) /** @@ -2395,7 +3533,7 @@ enum ENABLE_FLAGS_CODES #ifndef _COM_HS_DEFINED /** - * @brief Enumeration of handshake modes + * @brief Enumeration of handshake modes. */ enum COM_HANSHAKE_MODES { HS_NONE, HS_XONXOFF, HS_RTSCTS, N_COM_HS }; #define _COM_HS_DEFINED @@ -2403,27 +3541,27 @@ enum ENABLE_FLAGS_CODES #ifndef _COM_PARM_DEFINED /** - * @brief A data type to configure a serial port's baud rate + * @brief A data type to configure the baud rate of a serial port. * * @see ::MBG_BAUD_RATES */ typedef int32_t BAUD_RATE; /** - * @brief Indices used to identify a parameter in the framing string + * @brief Indices used to identify a parameter in the framing string. * * @see ::MBG_FRAMING_STRS */ enum MBG_FRAMING_STR_IDXS { F_DBITS, F_PRTY, F_STBITS }; /** - * @brief A structure to store the configuration of a serial port + * @brief A structure to store the configuration of a serial port. */ typedef struct { - BAUD_RATE baud_rate; ///< transmission speed, e.g. 19200L, see ::MBG_BAUD_RATES - char framing[4]; ///< ASCIIZ framing string, e.g. "8N1" or "7E2", see ::MBG_FRAMING_STRS - int16_t handshake; ///< handshake mode, yet only ::HS_NONE supported + BAUD_RATE baud_rate; ///< Transmission speed, e.g. 19200L, see ::MBG_BAUD_RATES. + char framing[4]; ///< ASCIIZ framing string, e.g. "8N1" or "7E2", see ::MBG_FRAMING_STRS. + int16_t handshake; ///< Handshake mode, yet only ::HS_NONE supported. } COM_PARM; @@ -2433,10 +3571,11 @@ enum ENABLE_FLAGS_CODES #define _mbg_swab_baud_rate( _p ) _mbg_swab32( _p ) #define _mbg_swab_com_parm( _p ) \ +do \ { \ _mbg_swab_baud_rate( &(_p)->baud_rate ); \ _mbg_swab16( &(_p)->handshake ); \ -} +} while ( 0 ) /** @@ -2527,19 +3666,19 @@ enum MBG_BAUD_RATE_CODES */ enum MBG_BAUD_RATE_MASKS { - MBG_PORT_HAS_300 = ( 1UL << MBG_BAUD_RATE_300 ), ///< see ::MBG_BAUD_RATE_300 - MBG_PORT_HAS_600 = ( 1UL << MBG_BAUD_RATE_600 ), ///< see ::MBG_BAUD_RATE_600 - MBG_PORT_HAS_1200 = ( 1UL << MBG_BAUD_RATE_1200 ), ///< see ::MBG_BAUD_RATE_1200 - MBG_PORT_HAS_2400 = ( 1UL << MBG_BAUD_RATE_2400 ), ///< see ::MBG_BAUD_RATE_2400 - MBG_PORT_HAS_4800 = ( 1UL << MBG_BAUD_RATE_4800 ), ///< see ::MBG_BAUD_RATE_4800 - MBG_PORT_HAS_9600 = ( 1UL << MBG_BAUD_RATE_9600 ), ///< see ::MBG_BAUD_RATE_9600 - MBG_PORT_HAS_19200 = ( 1UL << MBG_BAUD_RATE_19200 ), ///< see ::MBG_BAUD_RATE_19200 - MBG_PORT_HAS_38400 = ( 1UL << MBG_BAUD_RATE_38400 ), ///< see ::MBG_BAUD_RATE_38400 - MBG_PORT_HAS_57600 = ( 1UL << MBG_BAUD_RATE_57600 ), ///< see ::MBG_BAUD_RATE_57600 - MBG_PORT_HAS_115200 = ( 1UL << MBG_BAUD_RATE_115200 ), ///< see ::MBG_BAUD_RATE_115200 - MBG_PORT_HAS_230400 = ( 1UL << MBG_BAUD_RATE_230400 ), ///< see ::MBG_BAUD_RATE_230400 - MBG_PORT_HAS_460800 = ( 1UL << MBG_BAUD_RATE_460800 ), ///< see ::MBG_BAUD_RATE_460800 - MBG_PORT_HAS_921600 = ( 1UL << MBG_BAUD_RATE_921600 ) ///< see ::MBG_BAUD_RATE_921600 + MBG_PORT_HAS_300 = ( 1UL << MBG_BAUD_RATE_300 ), ///< See ::MBG_BAUD_RATE_300 + MBG_PORT_HAS_600 = ( 1UL << MBG_BAUD_RATE_600 ), ///< See ::MBG_BAUD_RATE_600 + MBG_PORT_HAS_1200 = ( 1UL << MBG_BAUD_RATE_1200 ), ///< See ::MBG_BAUD_RATE_1200 + MBG_PORT_HAS_2400 = ( 1UL << MBG_BAUD_RATE_2400 ), ///< See ::MBG_BAUD_RATE_2400 + MBG_PORT_HAS_4800 = ( 1UL << MBG_BAUD_RATE_4800 ), ///< See ::MBG_BAUD_RATE_4800 + MBG_PORT_HAS_9600 = ( 1UL << MBG_BAUD_RATE_9600 ), ///< See ::MBG_BAUD_RATE_9600 + MBG_PORT_HAS_19200 = ( 1UL << MBG_BAUD_RATE_19200 ), ///< See ::MBG_BAUD_RATE_19200 + MBG_PORT_HAS_38400 = ( 1UL << MBG_BAUD_RATE_38400 ), ///< See ::MBG_BAUD_RATE_38400 + MBG_PORT_HAS_57600 = ( 1UL << MBG_BAUD_RATE_57600 ), ///< See ::MBG_BAUD_RATE_57600 + MBG_PORT_HAS_115200 = ( 1UL << MBG_BAUD_RATE_115200 ), ///< See ::MBG_BAUD_RATE_115200 + MBG_PORT_HAS_230400 = ( 1UL << MBG_BAUD_RATE_230400 ), ///< See ::MBG_BAUD_RATE_230400 + MBG_PORT_HAS_460800 = ( 1UL << MBG_BAUD_RATE_460800 ), ///< See ::MBG_BAUD_RATE_460800 + MBG_PORT_HAS_921600 = ( 1UL << MBG_BAUD_RATE_921600 ) ///< See ::MBG_BAUD_RATE_921600 }; @@ -2602,16 +3741,16 @@ enum MBG_FRAMING_CODES */ enum MBG_FRAMING_MASKS { - MBG_PORT_HAS_7N2 = ( 1UL << MBG_FRAMING_7N2 ), ///< see ::MBG_FRAMING_7N2 - MBG_PORT_HAS_7E1 = ( 1UL << MBG_FRAMING_7E1 ), ///< see ::MBG_FRAMING_7E1 - MBG_PORT_HAS_7E2 = ( 1UL << MBG_FRAMING_7E2 ), ///< see ::MBG_FRAMING_7E2 - MBG_PORT_HAS_8N1 = ( 1UL << MBG_FRAMING_8N1 ), ///< see ::MBG_FRAMING_8N1 - MBG_PORT_HAS_8N2 = ( 1UL << MBG_FRAMING_8N2 ), ///< see ::MBG_FRAMING_8N2 - MBG_PORT_HAS_8E1 = ( 1UL << MBG_FRAMING_8E1 ), ///< see ::MBG_FRAMING_8E1 - MBG_PORT_HAS_7O1 = ( 1UL << MBG_FRAMING_7O1 ), ///< see ::MBG_FRAMING_7O1 - MBG_PORT_HAS_7O2 = ( 1UL << MBG_FRAMING_7O2 ), ///< see ::MBG_FRAMING_7O2 - MBG_PORT_HAS_8O1 = ( 1UL << MBG_FRAMING_8O1 ), ///< see ::MBG_FRAMING_8O1 - MBG_PORT_HAS_8E2 = ( 1UL << MBG_FRAMING_8E2 ) ///< see ::MBG_FRAMING_8E2 + MBG_PORT_HAS_7N2 = ( 1UL << MBG_FRAMING_7N2 ), ///< See ::MBG_FRAMING_7N2 + MBG_PORT_HAS_7E1 = ( 1UL << MBG_FRAMING_7E1 ), ///< See ::MBG_FRAMING_7E1 + MBG_PORT_HAS_7E2 = ( 1UL << MBG_FRAMING_7E2 ), ///< See ::MBG_FRAMING_7E2 + MBG_PORT_HAS_8N1 = ( 1UL << MBG_FRAMING_8N1 ), ///< See ::MBG_FRAMING_8N1 + MBG_PORT_HAS_8N2 = ( 1UL << MBG_FRAMING_8N2 ), ///< See ::MBG_FRAMING_8N2 + MBG_PORT_HAS_8E1 = ( 1UL << MBG_FRAMING_8E1 ), ///< See ::MBG_FRAMING_8E1 + MBG_PORT_HAS_7O1 = ( 1UL << MBG_FRAMING_7O1 ), ///< See ::MBG_FRAMING_7O1 + MBG_PORT_HAS_7O2 = ( 1UL << MBG_FRAMING_7O2 ), ///< See ::MBG_FRAMING_7O2 + MBG_PORT_HAS_8O1 = ( 1UL << MBG_FRAMING_8O1 ), ///< See ::MBG_FRAMING_8O1 + MBG_PORT_HAS_8E2 = ( 1UL << MBG_FRAMING_8E2 ) ///< See ::MBG_FRAMING_8E2 }; @@ -2733,10 +3872,11 @@ typedef struct } PORT_SETTINGS; #define _mbg_swab_port_settings( _p ) \ +do \ { \ _mbg_swab_com_parm( &(_p)->parm ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) /** @@ -2776,22 +3916,22 @@ enum MBG_COM_CFG_STATUS_BITS * * @anchor MBG_COM_CFG_STATUS_MASKS @{ */ -#define MBG_PS_MSK_BAUD_RATE_OVR_SW ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_SW ) ///< see ::MBG_PS_BIT_BAUD_RATE_OVR_SW -#define MBG_PS_MSK_BAUD_RATE_OVR_DEV ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_DEV ) ///< see ::MBG_PS_BIT_BAUD_RATE_OVR_DEV -#define MBG_PS_MSK_BAUD_RATE ( 1UL << MBG_PS_BIT_BAUD_RATE ) ///< see ::MBG_PS_BIT_BAUD_RATE -#define MBG_PS_MSK_FRAMING_OVR_SW ( 1UL << MBG_PS_BIT_FRAMING_OVR_SW ) ///< see ::MBG_PS_BIT_FRAMING_OVR_SW -#define MBG_PS_MSK_FRAMING_OVR_DEV ( 1UL << MBG_PS_BIT_FRAMING_OVR_DEV ) ///< see ::MBG_PS_BIT_FRAMING_OVR_DEV -#define MBG_PS_MSK_FRAMING ( 1UL << MBG_PS_BIT_FRAMING ) ///< see ::MBG_PS_BIT_FRAMING -#define MBG_PS_MSK_HS_OVR_SW ( 1UL << MBG_PS_BIT_HS_OVR_SW ) ///< see ::MBG_PS_BIT_HS_OVR_SW -#define MBG_PS_MSK_HS ( 1UL << MBG_PS_BIT_HS ) ///< see ::MBG_PS_BIT_HS -#define MBG_PS_MSK_STR_TYPE_OVR_SW ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_SW ) ///< see ::MBG_PS_BIT_STR_TYPE_OVR_SW -#define MBG_PS_MSK_STR_TYPE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_DEV ) ///< see ::MBG_PS_BIT_STR_TYPE_OVR_DEV -#define MBG_PS_MSK_STR_TYPE ( 1UL << MBG_PS_BIT_STR_TYPE ) ///< see ::MBG_PS_BIT_STR_TYPE -#define MBG_PS_MSK_STR_MODE_OVR_SW ( 1UL << MBG_PS_BIT_STR_MODE_OVR_SW ) ///< see ::MBG_PS_BIT_STR_MODE_OVR_SW -#define MBG_PS_MSK_STR_MODE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_MODE_OVR_DEV ) ///< see ::MBG_PS_BIT_STR_MODE_OVR_DEV -#define MBG_PS_MSK_STR_MODE ( 1UL << MBG_PS_BIT_STR_MODE ) ///< see ::MBG_PS_BIT_STR_MODE -#define MBG_PS_MSK_FLAGS_OVR_SW ( 1UL << MBG_PS_BIT_FLAGS_OVR_SW ) ///< see ::MBG_PS_BIT_FLAGS_OVR_SW -#define MBG_PS_MSK_FLAGS ( 1UL << MBG_PS_BIT_FLAGS ) ///< see ::MBG_PS_BIT_FLAGS +#define MBG_PS_MSK_BAUD_RATE_OVR_SW ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_SW ) ///< See ::MBG_PS_BIT_BAUD_RATE_OVR_SW +#define MBG_PS_MSK_BAUD_RATE_OVR_DEV ( 1UL << MBG_PS_BIT_BAUD_RATE_OVR_DEV ) ///< See ::MBG_PS_BIT_BAUD_RATE_OVR_DEV +#define MBG_PS_MSK_BAUD_RATE ( 1UL << MBG_PS_BIT_BAUD_RATE ) ///< See ::MBG_PS_BIT_BAUD_RATE +#define MBG_PS_MSK_FRAMING_OVR_SW ( 1UL << MBG_PS_BIT_FRAMING_OVR_SW ) ///< See ::MBG_PS_BIT_FRAMING_OVR_SW +#define MBG_PS_MSK_FRAMING_OVR_DEV ( 1UL << MBG_PS_BIT_FRAMING_OVR_DEV ) ///< See ::MBG_PS_BIT_FRAMING_OVR_DEV +#define MBG_PS_MSK_FRAMING ( 1UL << MBG_PS_BIT_FRAMING ) ///< See ::MBG_PS_BIT_FRAMING +#define MBG_PS_MSK_HS_OVR_SW ( 1UL << MBG_PS_BIT_HS_OVR_SW ) ///< See ::MBG_PS_BIT_HS_OVR_SW +#define MBG_PS_MSK_HS ( 1UL << MBG_PS_BIT_HS ) ///< See ::MBG_PS_BIT_HS +#define MBG_PS_MSK_STR_TYPE_OVR_SW ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_SW ) ///< See ::MBG_PS_BIT_STR_TYPE_OVR_SW +#define MBG_PS_MSK_STR_TYPE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_TYPE_OVR_DEV ) ///< See ::MBG_PS_BIT_STR_TYPE_OVR_DEV +#define MBG_PS_MSK_STR_TYPE ( 1UL << MBG_PS_BIT_STR_TYPE ) ///< See ::MBG_PS_BIT_STR_TYPE +#define MBG_PS_MSK_STR_MODE_OVR_SW ( 1UL << MBG_PS_BIT_STR_MODE_OVR_SW ) ///< See ::MBG_PS_BIT_STR_MODE_OVR_SW +#define MBG_PS_MSK_STR_MODE_OVR_DEV ( 1UL << MBG_PS_BIT_STR_MODE_OVR_DEV ) ///< See ::MBG_PS_BIT_STR_MODE_OVR_DEV +#define MBG_PS_MSK_STR_MODE ( 1UL << MBG_PS_BIT_STR_MODE ) ///< See ::MBG_PS_BIT_STR_MODE +#define MBG_PS_MSK_FLAGS_OVR_SW ( 1UL << MBG_PS_BIT_FLAGS_OVR_SW ) ///< See ::MBG_PS_BIT_FLAGS_OVR_SW +#define MBG_PS_MSK_FLAGS ( 1UL << MBG_PS_BIT_FLAGS ) ///< See ::MBG_PS_BIT_FLAGS /** @} anchor MBG_COM_CFG_STATUS_MASKS */ @@ -2811,16 +3951,17 @@ enum MBG_COM_CFG_STATUS_BITS */ typedef struct { - uint16_t idx; ///< port index, 0..::RECEIVER_INFO::n_com_ports-1 + MBG_MSG_IDX idx; ///< Port index, 0..::RECEIVER_INFO::n_com_ports-1 PORT_SETTINGS port_settings; } PORT_SETTINGS_IDX; #define _mbg_swab_port_settings_idx( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_port_settings( &(_p)->port_settings ); \ -} +} while ( 0 ) /** @@ -2839,11 +3980,12 @@ typedef struct uint32_t supp_framings; ///< bit mask of framings supp. by this port, see ::MBG_FRAMING_MASKS uint32_t supp_str_types; ///< bit mask of string types supp. by this port, i.e. bit 0 set if str_type[0] is supp. uint32_t reserved; ///< reserved for future use, currently always 0 - uint32_t flags; ///< see ::PORT_INFO_FLAGS + uint32_t flags; ///< See ::PORT_INFO_FLAGS } PORT_INFO; #define _mbg_swab_port_info( _p ) \ +do \ { \ _mbg_swab_port_settings( &(_p)->port_settings ); \ _mbg_swab32( &(_p)->supp_baud_rates ); \ @@ -2851,7 +3993,7 @@ typedef struct _mbg_swab32( &(_p)->supp_str_types ); \ _mbg_swab32( &(_p)->reserved ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) /** @@ -2874,8 +4016,8 @@ enum PORT_INFO_FLAG_BITS */ enum PORT_INFO_FLAGS { - PORT_INFO_FLAG_PORT_INVISIBLE = ( 1UL << PORT_INFO_FLAG_BIT_PORT_INVISIBLE ), ///< see ::PORT_INFO_FLAG_BIT_PORT_INVISIBLE - PORT_INFO_FLAG_BIN_PROT_HS = ( 1UL << PORT_INFO_FLAG_BIT_BIN_PROT_HS ) ///< see ::PORT_INFO_FLAG_BIT_BIN_PROT_HS + PORT_INFO_FLAG_PORT_INVISIBLE = ( 1UL << PORT_INFO_FLAG_BIT_PORT_INVISIBLE ), ///< See ::PORT_INFO_FLAG_BIT_PORT_INVISIBLE + PORT_INFO_FLAG_BIN_PROT_HS = ( 1UL << PORT_INFO_FLAG_BIT_BIN_PROT_HS ) ///< See ::PORT_INFO_FLAG_BIT_BIN_PROT_HS }; @@ -2892,16 +4034,17 @@ enum PORT_INFO_FLAGS */ typedef struct { - uint16_t idx; ///< port index, 0..::RECEIVER_INFO::n_com_ports-1 + MBG_MSG_IDX idx; ///< Port index, 0..::RECEIVER_INFO::n_com_ports-1 PORT_INFO port_info; } PORT_INFO_IDX; #define _mbg_swab_port_info_idx( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_port_info( &(_p)->port_info ); \ -} +} while ( 0 ) /** @@ -2926,10 +4069,11 @@ typedef struct } STR_TYPE_INFO; #define _mbg_swab_str_type_info( _p ) \ +do \ { \ _mbg_swab32( &(_p)->supp_modes ); \ _mbg_swab16( &(_p)->flags ); \ -} +} while ( 0 ) @@ -2946,16 +4090,17 @@ typedef struct */ typedef struct { - uint16_t idx; ///< string type index, 0..::RECEIVER_INFO::n_str_type-1 + MBG_MSG_IDX idx; ///< String type index, 0..::RECEIVER_INFO::n_str_type-1 STR_TYPE_INFO str_type_info; } STR_TYPE_INFO_IDX; #define _mbg_swab_str_type_info_idx( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_str_type_info( &(_p)->str_type_info ); \ -} +} while ( 0 ) /** @@ -2974,6 +4119,7 @@ enum STR_MODES STR_PER_MIN, ///< transmission automatically if minute changes STR_AUTO, ///< transmission automatically if required, e.g. on capture event STR_ON_REQ_SEC, ///< transmission if second changes and a request has been received before + STR_CR_ON_SEC, ///< transmisson automatically if second changes, but carriage return (0x13) on time N_STR_MODE ///< the number of known modes }; @@ -2988,11 +4134,12 @@ enum STR_MODES */ enum STR_MODE_MASKS { - MSK_STR_ON_REQ = ( 1UL << STR_ON_REQ ), ///< see ::STR_ON_REQ - MSK_STR_PER_SEC = ( 1UL << STR_PER_SEC ), ///< see ::STR_PER_SEC - MSK_STR_PER_MIN = ( 1UL << STR_PER_MIN ), ///< see ::STR_PER_MIN - MSK_STR_AUTO = ( 1UL << STR_AUTO ), ///< see ::STR_AUTO - MSK_STR_ON_REQ_SEC = ( 1UL << STR_ON_REQ_SEC ) ///< see ::STR_ON_REQ_SEC + MSK_STR_ON_REQ = ( 1UL << STR_ON_REQ ), ///< See ::STR_ON_REQ + MSK_STR_PER_SEC = ( 1UL << STR_PER_SEC ), ///< See ::STR_PER_SEC + MSK_STR_PER_MIN = ( 1UL << STR_PER_MIN ), ///< See ::STR_PER_MIN + MSK_STR_AUTO = ( 1UL << STR_AUTO ), ///< See ::STR_AUTO + MSK_STR_ON_REQ_SEC = ( 1UL << STR_ON_REQ_SEC ), ///< See ::STR_ON_REQ_SEC + MSK_STR_CR_ON_SEC = ( 1UL << STR_CR_ON_SEC ) ///< See ::STR_CR_ON_SEC }; @@ -3007,7 +4154,8 @@ enum STR_MODE_MASKS "1 sec", \ "1 min", \ "auto", \ - "'?' sec" \ + "'?' sec", \ + "<CR> on sec" \ } @@ -3023,6 +4171,7 @@ enum STR_MODE_MASKS #define ENG_MODE_NAME_STR_PER_MIN "per minute" #define ENG_MODE_NAME_STR_AUTO "automatically" #define ENG_MODE_NAME_STR_ON_REQ_SEC "sec after request" +#define ENG_MODE_NAME_STR_CR_ON_SEC "per second, <CR> on second change" /** @@ -3038,7 +4187,8 @@ enum STR_MODE_MASKS ENG_MODE_NAME_STR_PER_SEC, \ ENG_MODE_NAME_STR_PER_MIN, \ ENG_MODE_NAME_STR_AUTO, \ - ENG_MODE_NAME_STR_ON_REQ_SEC \ + ENG_MODE_NAME_STR_ON_REQ_SEC, \ + ENG_MODE_NAME_STR_CR_ON_SEC \ } @@ -3064,6 +4214,52 @@ enum STR_MODE_MASKS +/** + * @brief The number of string types supported by legacy DCF77 receivers + * + * For receivers supporting a ::RECEIVER_INFO this should be determined + * from ::RECEIVER_INFO::n_str_type. + * + * @see ::DEFAULT_SUPP_STR_TYPES_DCF + */ +#define DEFAULT_N_STR_TYPE_DCF 1 + +/** + * @brief Bit mask of string types supported by legacy DCF77 receivers + * + * For receivers supporting a ::RECEIVER_INFO this should be determined + * from ::PORT_INFO::supp_str_types. + * + * @see ::DEFAULT_N_STR_TYPE_DCF + */ +#define DEFAULT_SUPP_STR_TYPES_DCF \ + ( ( 1UL << DEFAULT_N_STR_TYPE_DCF ) - 1 ) + + + +/** + * @brief The number of string types supported by legacy GPS receivers + * + * For receivers supporting a ::RECEIVER_INFO this should be determined + * from ::RECEIVER_INFO::n_str_type. + * + * @see ::DEFAULT_SUPP_STR_TYPES_GPS + */ +#define DEFAULT_N_STR_TYPE_GPS 2 + +/** + * @brief Bit mask of string types supported by legacy GPS receivers + * + * For receivers supporting a ::RECEIVER_INFO this should be determined + * from ::PORT_INFO::supp_str_types. + * + * @see ::DEFAULT_N_STR_TYPE_GPS + */ +#define DEFAULT_SUPP_STR_TYPES_GPS \ + ( ( 1UL << DEFAULT_N_STR_TYPE_GPS ) - 1 ) + + + /* * The number of serial ports which are at least available * even with very old GPS receiver models. For devices providing @@ -3083,17 +4279,20 @@ enum STR_MODE_MASKS /** * @brief A The structure used to store the configuration of two serial ports * - * @deprecated This structure is deprecated, ::PORT_SETTINGS and related structures - * should be used instead, if supported by the device. + * @deprecated This structure is deprecated and should only be used + * with legacy GPS receivers that don't provide a ::RECEIVER_INFO structure. + * + * @see ::PORT_SETTINGS and ::PORT_INFO for current devices */ typedef struct { COM_PARM com[DEFAULT_N_COM]; ///< COM0 and COM1 settings - uint8_t mode[DEFAULT_N_COM]; ///< COM0 and COM1 output mode + uint8_t mode[DEFAULT_N_COM]; ///< COM0 and COM1 output mode, see ::LGCY_STR_MODES } PORT_PARM; #define _mbg_swab_port_parm( _p ) \ +do \ { \ int i; \ for ( i = 0; i < DEFAULT_N_COM; i++ ) \ @@ -3101,29 +4300,37 @@ typedef struct _mbg_swab_com_parm( &(_p)->com[i] ); \ /* no need to swap mode byte */ \ } \ -} +} while ( 0 ) + /** - * @brief Deprecated codes for mode of operation + * @brief Deprecated codes for serial string modes * * @deprecated These codes have been used with the - * deprecated ::PORT_PARM::mode. They are only still - * defined for compatibility with older devices. + * deprecated ::PORT_PARM::mode field and are still + * defined for compatibility reasons. * * @see ::STR_MODES */ -enum +enum LGCY_STR_MODES { - /* STR_ON_REQ, defined above */ - /* STR_PER_SEC, defined above */ - /* STR_PER_MIN, defined above */ - N_STR_MODE_0 = STR_AUTO, /* COM0 and COM1 */ - STR_UCAP = N_STR_MODE_0, - STR_UCAP_REQ, - N_STR_MODE_1 /* COM1 only */ + LGCY_STR_ON_REQ, ///< On request '?' only, same as ::STR_ON_REQ, COM0 and COM1 + LGCY_STR_PER_SEC, ///< Per second, same as ::STR_PER_SEC, COM0 and COM1 + LGCY_STR_PER_MIN, ///< Per minute, same as ::STR_PER_MIN, COM0 and COM1 + LGCY_STR_UCAP, ///< Automatically, when a capture event has occurred, COM1 only + LGCY_STR_UCAP_REQ, ///< On request only, if a capture event is available, COM1 only + N_LGCY_STR_MODES ///< Number of legacy string modes }; +#if _IS_MBG_FIRMWARE // Old symbols for source code compatibility ... + #define STR_UCAP LGCY_STR_UCAP // Same numeric value as ::STR_AUTO + #define STR_UCAP_REQ LGCY_STR_UCAP_REQ // Same numeric value as ::STR_ON_REQ_SEC, but different function + + #define N_STR_MODE_0 ( LGCY_STR_PER_MIN + 1 ) // Number of modes supp. for COM0 + #define N_STR_MODE_1 N_LGCY_STR_MODES // Number of modes supp. for COM1 +#endif + /** @@ -3131,8 +4338,8 @@ enum * * The following definitions are used to configure an optional * on-board IRIG input or output. Which frame types are supported - * by a device depends on the device type, and may eventually - * depend on the device's firmware version. + * by a device depends on the device type, and may depend on the + * firmware version of the device. * * All IRIG frames transport the day-of-year number plus the time-of-day, * and include a control field segment which can transport user defined @@ -3142,6 +4349,50 @@ enum * well defined extensions like the year number, local time offset, DST status, * etc., in the control fields: * + * The following specification can be found in IRIG Standard 200-04 (September 2004): + * + * Format A: 1k pps + * Format B: 100 pps + * Format D: 1 ppm + * Format E: 10 pps + * Format G: 10k pps + * Format H: 1 pps + * + * 1st digit: Modulation Frequency + * 0 Pulse width code + * 1 Sine wave, amplitude modulated + * 2 Manchester modulated + * + * 2nd digit: Frequency / Resolution + * 0: No carrier / index count interval + * 1: 100 Hz / 10 ms + * 2: 1 kHz / 1 ms + * 3: 10 kHz / 0.1 ms + * 4: 100 kHz / 10 ms + * 5: 1 MHz / 1 ms + * + * 3rd digit: Coded expressions + * 0: DOY+TOD, CF, SBS + * 1: DOY+TOD, CF + * 2: DOY+TOD + * 3: DOY+TOD, SBS + * 4: DOY+TOD, Year, CF, SBS + * 5: DOY+TOD, Year, CF + * 6: DOY+TOD, Year + * 7: DOY+TOD, Year, SBS + * + * + * Table of Permissible Code Formats + * + * Letter 1st digit 2nd digit 3rd digit + * ---------------------------------------------- + * A 0,1,2 0,3,4,5 0,1,2,3,4,5,6,7 + * B 0,1,2 0,2,3,4,5 0,1,2,3,4,5,6,7 + * D 0,1 0,1,2 1,2 + * E 0,1 0,1,2 1,2,5,6 + * G 0,1,2 0,4,5 1,2,5,6 + * H 0,1 0,1,2 1,2 + * * - Known IRIG signal code types: * - \b A002: 1000 bps, DCLS, time-of-year * - \b A003: 1000 bps, DCLS, time-of-year, SBS @@ -3184,9 +4435,9 @@ enum * of the IEEE 1344 standard from 1995. These codes provide the same extensions as IEEE 1344 * but unfortunately determine that the %UTC offset has to be applied with reversed sign. * - * For example, if a -6 hours UTC offset is transmitted in the time code:<br> - * IEEE 1344: (IRIG time 14:43:27 h) - (offs -6 h) = (UTC 20:43:27)<br> - * IEEE C37.118: (IRIG time 14:43:27 h) + (offs -6 h) = (UTC 08:43:27)<br> + * For example, if a -6 hours %UTC offset is transmitted in the time code:<br> + * IEEE 1344: (IRIG time 14:43:27 h) - (offs -6 h) = (%UTC 20:43:27)<br> + * IEEE C37.118: (IRIG time 14:43:27 h) + (offs -6 h) = (%UTC 08:43:27)<br> * * @see @ref MSK_ICODE_RX_UTC_OFFS_ADD and @ref MSK_ICODE_RX_UTC_OFFS_SUB * @@ -3230,38 +4481,42 @@ enum ICODE_TX_CODES ICODE_TX_TXC101, ICODE_TX_E002_E112, ICODE_TX_NASA36, + ICODE_TX_A006_A136, + ICODE_TX_A007_A137, N_ICODE_TX ///< number of known codes }; /** - * @brief Initializers for timecode format name strings + * @brief Initializers for TX timecode format name strings * * @see ::ICODE_TX_CODES */ -#define DEFAULT_ICODE_TX_NAMES \ -{ \ - "B002+B122", \ - "B003+B123", \ - "A002+A132", \ - "A003+A133", \ - "AFNOR NF S87-500", \ - "IEEE1344", \ - "B220(1344) DCLS", \ - "B222 DCLS", \ - "B223 DCLS", \ - "B006+B126", \ - "B007+B127", \ - "G002+G142", \ - "G006+G146", \ - "C37.118", \ - "TXC-101 DTR-6", \ - "E002+E112", \ - "NASA 36" \ -} - -/** - * @brief Initializers for short timecode format name strings +#define DEFAULT_ICODE_TX_NAMES \ +{ \ + /* B002_B122 */ "B002+B122", \ + /* B003_B123 */ "B003+B123", \ + /* A002_A132 */ "A002+A132", \ + /* A003_A133 */ "A003+A133", \ + /* AFNOR */ "AFNOR NF S87-500", \ + /* IEEE1344 */ "IEEE 1344", \ + /* B2201344 */ "B220(1344) DCLS", \ + /* B222 */ "B222 DCLS", \ + /* B223 */ "B223 DCLS", \ + /* B006_B126 */ "B006+B126", \ + /* B007_B127 */ "B007+B127", \ + /* G002_G142 */ "G002+G142", \ + /* G006_G146 */ "G006+G146", \ + /* C37118 */ "IEEE C37.118", \ + /* TXC101 */ "TXC-101 DTR-6", \ + /* E002_E112 */ "E002+E112", \ + /* NASA36 */ "NASA 36", \ + /* A006_A136 */ "A006+A136", \ + /* A007_A137 */ "A007+A137" \ +} + +/** + * @brief Initializers for short TX timecode format name strings * * @note Must not be longer than 10 printable characters * @@ -3269,55 +4524,59 @@ enum ICODE_TX_CODES */ #define DEFAULT_ICODE_TX_NAMES_SHORT \ { \ - "B002+B122", \ - "B003+B123", \ - "A002+A132", \ - "A003+A133", \ - "AFNOR NF S", \ - "IEEE1344", \ - "B220/1344", \ - "B222 DC", \ - "B223 DC", \ - "B006+B126", \ - "B007+B127", \ - "G002+G142", \ - "G006+G146", \ - "C37.118", \ - "TXC-101", \ - "E002+E112", \ - "NASA 36" \ + /* B002_B122 */ "B002+B122", \ + /* B003_B123 */ "B003+B123", \ + /* A002_A132 */ "A002+A132", \ + /* A003_A133 */ "A003+A133", \ + /* AFNOR */ "AFNOR NF S", \ + /* IEEE1344 */ "IEEE 1344", \ + /* B2201344 */ "B220/1344", \ + /* B222 */ "B222 DC", \ + /* B223 */ "B223 DC", \ + /* B006_B126 */ "B006+B126", \ + /* B007_B127 */ "B007+B127", \ + /* G002_G142 */ "G002+G142", \ + /* G006_G146 */ "G006+G146", \ + /* C37118 */ "C37.118", \ + /* TXC101 */ "TXC-101", \ + /* E002_E112 */ "E002+E112", \ + /* NASA36 */ "NASA 36", \ + /* A006_A136 */ "A006+A136", \ + /* A007_A137 */ "A007+A137" \ } /** - * @brief Initializers for English format description strings + * @brief Initializers for English TX format description strings * * @see ::ICODE_TX_CODES */ -#define DEFAULT_ICODE_TX_DESCRIPTIONS_ENG \ -{ \ - "100 bps, DCLS or 1 kHz carrier", \ - "100 bps, DCLS or 1 kHz carrier, SBS", \ - "1000 bps, DCLS or 10 kHz carrier", \ - "1000 bps, DCLS or 10 kHz carrier, SBS", \ - "100 bps, DCLS or 1 kHz carrier, SBS, complete date", \ - "100 bps, DCLS or 1 kHz carrier, SBS, complete date, time zone info", \ - "100 bps, Manchester enc., DCLS only, SBS, complete date, time zone info", \ - "100 bps, Manchester enc., DCLS only", \ - "100 bps, Manchester enc., DCLS only, SBS", \ - "100 bps, DCLS or 1 kHz carrier, complete date", \ - "100 bps, DCLS or 1 kHz carrier, complete date, SBS", \ - "10 kbps, DCLS or 100 kHz carrier", \ - "10 kbps, DCLS or 100 kHz carrier, complete date", \ - "like IEEE1344, but UTC offset with reversed sign", \ - "code from TV time sync device TXC-101 DTR-6", \ - "10 bps, DCLS or 100 Hz carrier", \ - "100 bps, DCLS or 1 kHz carrier" \ +#define DEFAULT_ICODE_TX_DESCRIPTIONS_ENG \ +{ \ + /* B002_B122 */ "100 bps, DCLS or 1 kHz carrier", \ + /* B003_B123 */ "100 bps, DCLS or 1 kHz carrier, SBS", \ + /* A002_A132 */ "1000 bps, DCLS or 10 kHz carrier", \ + /* A003_A133 */ "1000 bps, DCLS or 10 kHz carrier, SBS", \ + /* AFNOR */ "100 bps, DCLS or 1 kHz carrier, complete date, SBS", \ + /* IEEE1344 */ "100 bps, DCLS or 1 kHz carrier, 2 digit year number, SBS, UTC offset, DST and Leap sec status", \ + /* B2201344 */ "100 bps, Manchester enc., DCLS only, 2 digit year number, SBS, UTC offset, DST and Leap sec status", \ + /* B222 */ "100 bps, Manchester enc., DCLS only", \ + /* B223 */ "100 bps, Manchester enc., DCLS only, SBS", \ + /* B006_B126 */ "100 bps, DCLS or 1 kHz carrier, 2 digit year number", \ + /* B007_B127 */ "100 bps, DCLS or 1 kHz carrier, 2 digit year number, SBS", \ + /* G002_G142 */ "10 kbps, DCLS or 100 kHz carrier", \ + /* G006_G146 */ "10 kbps, DCLS or 100 kHz carrier, 2 digit year number", \ + /* C37118 */ "100 bps, DCLS or 1 kHz carrier, 2 digit year number, SBS, UTC offs. reverse to 1344, DST/Leap sec status", \ + /* TXC101 */ "code from TV time sync device TXC-101 DTR-6", \ + /* E002_E112 */ "10 bps, DCLS or 100 Hz carrier", \ + /* NASA36 */ "100 bps, DCLS or 1 kHz carrier", \ + /* A006_A136 */ "1000 bps, DCLS or 10 kHz carrier, 2 digit year number", \ + /* A007_A137 */ "1000 bps, DCLS or 10 kHz carrier, 2 digit year number, SBS" \ } /** - * @brief Bit masks used with ::IRIG_INFO::supp_codes + * @brief Bit masks used with ::IRIG_INFO::supp_codes for TX * * These bit masks are used with timecode receivers only * @@ -3344,12 +4603,14 @@ enum ICODE_TX_CODES #define MSK_ICODE_TX_TXC101 ( 1UL << ICODE_TX_TXC101 ) #define MSK_ICODE_TX_E002_E112 ( 1UL << ICODE_TX_E002_E112 ) #define MSK_ICODE_TX_NASA36 ( 1UL << ICODE_TX_NASA36 ) +#define MSK_ICODE_TX_A006_A136 ( 1UL << ICODE_TX_A006_A136 ) +#define MSK_ICODE_TX_A007_A137 ( 1UL << ICODE_TX_A007_A137 ) /** @} anchor ICODE_TX_MASKS */ /** - * @brief A mask of IRIG formats with manchester encoded DC output + * @brief A mask of IRIG TX formats with manchester encoded DC output */ #define MSK_ICODE_TX_DC_MANCH \ ( \ @@ -3359,7 +4620,7 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats with 100 Hz carrier + * @brief A mask of IRIG TX formats with 100 Hz carrier */ #define MSK_ICODE_TX_100HZ \ ( \ @@ -3367,7 +4628,7 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats with 1 kHz carrier + * @brief A mask of IRIG TX formats with 1 kHz carrier */ #define MSK_ICODE_TX_1KHZ \ ( \ @@ -3385,16 +4646,18 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats with 10 kHz carrier + * @brief A mask of IRIG TX formats with 10 kHz carrier */ #define MSK_ICODE_TX_10KHZ \ ( \ MSK_ICODE_TX_A002_A132 | \ - MSK_ICODE_TX_A003_A133 \ + MSK_ICODE_TX_A003_A133 | \ + MSK_ICODE_TX_A006_A136 | \ + MSK_ICODE_TX_A007_A137 \ ) /** - * @brief A mask of IRIG formats with 100 kHz carrier + * @brief A mask of IRIG TX formats with 100 kHz carrier */ #define MSK_ICODE_TX_100KHZ \ ( \ @@ -3403,7 +4666,7 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats with 10 bps data rate + * @brief A mask of IRIG TX formats with 10 bps data rate */ #define MSK_ICODE_TX_10BPS \ ( \ @@ -3411,7 +4674,7 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats with 100 bps data rate + * @brief A mask of IRIG TX formats with 100 bps data rate */ #define MSK_ICODE_TX_100BPS \ ( \ @@ -3425,16 +4688,18 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats with 1000 bps data rate + * @brief A mask of IRIG TX formats with 1000 bps data rate */ #define MSK_ICODE_TX_1000BPS \ ( \ MSK_ICODE_TX_A002_A132 | \ - MSK_ICODE_TX_A003_A133 \ + MSK_ICODE_TX_A003_A133 | \ + MSK_ICODE_TX_A006_A136 | \ + MSK_ICODE_TX_A007_A137 \ ) /** - * @brief A mask of IRIG formats with 10 kbps data rate + * @brief A mask of IRIG TX formats with 10 kbps data rate */ #define MSK_ICODE_TX_10000BPS \ ( \ @@ -3443,18 +4708,20 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats supporting 10ths of seconds + * @brief A mask of IRIG TX formats supporting 10ths of seconds */ #define MSK_ICODE_TX_HAS_SEC10THS \ ( \ MSK_ICODE_TX_A002_A132 | \ MSK_ICODE_TX_A003_A133 | \ MSK_ICODE_TX_G002_G142 | \ - MSK_ICODE_TX_G006_G146 \ + MSK_ICODE_TX_G006_G146 | \ + MSK_ICODE_TX_A006_A136 | \ + MSK_ICODE_TX_A007_A137 \ ) /** - * @brief A mask of IRIG formats supporting 100ths of seconds + * @brief A mask of IRIG TX formats supporting 100ths of seconds */ #define MSK_ICODE_TX_HAS_SEC100THS \ ( \ @@ -3463,19 +4730,60 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats supporting a 2 digit year number + * @brief A mask of IRIG TX formats providing a short year number after P5 + * + * The IEEE codes, the AFNOR codes, and some IRIG codes provide a + * 2 digit year number after position identifier P5. However, some + * IRIG G codes provide a 100ths-of-seconds field after P5,and + * eventually provide a year number after P6. + * + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 + * @see @ref MSK_ICODE_TX_HAS_ANY_SHORT_YEAR */ -#define MSK_ICODE_TX_HAS_SHORT_YEAR \ -( \ - MSK_ICODE_TX_AFNOR | \ - MSK_ICODE_TX_IEEE1344 | \ - MSK_ICODE_TX_B006_B126 | \ - MSK_ICODE_TX_B007_B127 | \ - MSK_ICODE_TX_C37118 \ +#define MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 \ +( \ + MSK_ICODE_TX_AFNOR | \ + MSK_ICODE_TX_IEEE1344 | \ + MSK_ICODE_TX_B2201344 | \ + MSK_ICODE_TX_B006_B126 | \ + MSK_ICODE_TX_B007_B127 | \ + MSK_ICODE_TX_C37118 | \ + MSK_ICODE_TX_A006_A136 | \ + MSK_ICODE_TX_A007_A137 \ ) /** - * @brief A mask of IRIG formats supporting TFOM + * @brief A mask of IRIG TX formats providing a short year number after P6 + * + * While most time codes that provide a year number do this after P5, + * there are some IRIG codes which provide a 100ths-of-seconds field + * at that position, and eventually provide a year number after P6. + * + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 + * @see @ref MSK_ICODE_TX_HAS_ANY_SHORT_YEAR + */ + #define MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 \ +( \ + MSK_ICODE_TX_G006_G146 \ +) + +/** + * @brief A mask of IRIG TX formats providing a short year number in general + * + * Depending on the code format, the year number can be transmitted + * either after position identifier P5, or after P6. + * + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 + * @see @ref MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 + */ +#define MSK_ICODE_TX_HAS_ANY_SHORT_YEAR \ +( \ + MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P5 | \ + MSK_ICODE_TX_HAS_SHORT_YEAR_AFTER_P6 \ +) + +/** + * @brief A mask of IRIG TX formats supporting TFOM */ #define MSK_ICODE_TX_HAS_TFOM \ ( \ @@ -3484,7 +4792,7 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats supporting CTQ continuous time quality + * @brief A mask of IRIG TX formats supporting CTQ continuous time quality * * This has been introduced in IEEE C37.118.1-2011 */ @@ -3495,7 +4803,7 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats supporting time zone information + * @brief A mask of IRIG TX formats supporting time zone information */ #define MSK_ICODE_TX_HAS_TZI \ ( \ @@ -3504,11 +4812,11 @@ enum ICODE_TX_CODES ) /** - * @brief IRIG formats where UTC offset must be subtracted to yield UTC + * @brief IRIG TX formats where %UTC offset must be subtracted to yield %UTC * - * A mask of IRIG formats where the decoded UTC offset must be - * subtracted from the time decoded from the IRIG signal to yield UTC, e.g.:<br> - * (IRIG time 14:43:27 h) - (offs -6 h) = (UTC 20:43:27) + * A mask of IRIG formats where the decoded %UTC offset must be + * subtracted from the time decoded from the IRIG signal to yield %UTC, e.g.:<br> + * (IRIG time 14:43:27 h) - (offs -6 h) = (%UTC 20:43:27) */ #define MSK_ICODE_TX_UTC_OFFS_SUB \ ( \ @@ -3516,11 +4824,11 @@ enum ICODE_TX_CODES ) /** - * @brief IRIG formats where UTC offset must be added to yield UTC + * @brief IRIG TX formats where %UTC offset must be added to yield %UTC * - * A mask of IRIG formats where the decoded UTC offset must be - * added to the time decoded from the IRIG signal to yield UTC, e.g.:<br> - * (IRIG time 14:43:27 h) + (offs -6 h) = (UTC 08:43:27) + * A mask of IRIG formats where the decoded %UTC offset must be + * added to the time decoded from the IRIG signal to yield %UTC, e.g.:<br> + * (IRIG time 14:43:27 h) + (offs -6 h) = (%UTC 08:43:27) */ #define MSK_ICODE_TX_UTC_OFFS_ADD \ ( \ @@ -3528,7 +4836,7 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats supporting a day of week number + * @brief A mask of IRIG TX formats supporting a day of week number */ #define MSK_ICODE_TX_HAS_AFNOR_WDAY \ ( \ @@ -3537,7 +4845,7 @@ enum ICODE_TX_CODES ) /** - * @brief A mask of IRIG formats supporting a date (day-of-month, month) + * @brief A mask of IRIG TX formats supporting a date (day-of-month, month) */ #define MSK_ICODE_TX_HAS_AFNOR_DATE \ ( \ @@ -3547,7 +4855,7 @@ enum ICODE_TX_CODES /** - * @brief The default mask of IRIG formats supported by IRIG transmitters + * @brief The default mask of IRIG TX formats supported by IRIG transmitters * * @note The formats which are actually supported should be retrieved * from the device @@ -3589,8 +4897,8 @@ enum ICODE_RX_CODES ICODE_RX_IEEE1344_DC, ///< DCLS ICODE_RX_B126_B127, ///< modulated ICODE_RX_B006_B007, ///< DCLS - ICODE_RX_G142_G146, ///< modulated - ICODE_RX_G002_G006, ///< DCLS + ICODE_RX_G142, ///< modulated (G143 is undefined, SBS not supported with Gxxx) + ICODE_RX_G002, ///< DCLS (G003 is undefined, SBS not supported with Gxxx) ICODE_RX_C37118, ///< modulated ICODE_RX_C37118_DC, ///< DCLS ICODE_RX_TXC101, ///< modulated @@ -3599,101 +4907,117 @@ enum ICODE_RX_CODES ICODE_RX_E002, ///< DCLS ICODE_RX_NASA36, ///< modulated ICODE_RX_NASA36_DC, ///< DCLS + ICODE_RX_A136_A137, ///< modulated + ICODE_RX_A006_A007, ///< DCLS + ICODE_RX_G146, ///< modulated (G147 is undefined, SBS not supported with Gxxx) + ICODE_RX_G006, ///< DCLS (G007 is undefined, SBS not supported with Gxxx) N_ICODE_RX ///< the number of known codes }; /** - * @brief Initializers for timecode format name strings + * @brief Initializers for RX timecode format name strings * * @see ::ICODE_RX_CODES */ #define DEFAULT_ICODE_RX_NAMES \ { \ - "B122/B123", \ - "A132/A133", \ - "B002/B003 (DCLS)", \ - "A002/A003 (DCLS)", \ - "AFNOR NF S87-500", \ - "AFNOR NF S87-500 (DCLS)", \ - "IEEE1344", \ - "IEEE1344 (DCLS)", \ - "B126/B127", \ - "B006/B007 (DCLS)", \ - "G142/G146", \ - "G002/G006 (DCLS)", \ - "C37.118", \ - "C37.118 (DCLS)", \ - "TXC-101 DTR-6", \ - "TXC-101 DTR-6 (DCLS)", \ - "E112", \ - "E002 (DCLS)", \ - "NASA-36", \ - "NASA-36 (DCLS)" \ -} - -/** - * @brief Initializers for short timecode format name strings + /* B122_B123 */ "B122/B123", \ + /* A132_A133 */ "A132/A133", \ + /* B002_B003 */ "B002/B003 (DCLS)", \ + /* A002_A003 */ "A002/A003 (DCLS)", \ + /* AFNOR */ "AFNOR NF S87-500", \ + /* AFNOR_DC */ "AFNOR NF S87-500 (DCLS)", \ + /* IEEE1344 */ "IEEE1344", \ + /* IEEE1344_DC */ "IEEE1344 (DCLS)", \ + /* B126_B127 */ "B126/B127", \ + /* B006_B007 */ "B006/B007 (DCLS)", \ + /* G142 */ "G142", \ + /* G002 */ "G002 (DCLS)", \ + /* C37118 */ "C37.118", \ + /* C37118_DC */ "C37.118 (DCLS)", \ + /* TXC101 */ "TXC-101 DTR-6", \ + /* TXC101_DC */ "TXC-101 DTR-6 (DCLS)", \ + /* E112 */ "E112", \ + /* E002 */ "E002 (DCLS)", \ + /* NASA36 */ "NASA-36", \ + /* NASA36_DC */ "NASA-36 (DCLS)", \ + /* A136_A137 */ "A136/A137", \ + /* A006_A007 */ "A006/A007 (DCLS)", \ + /* G146 */ "G146", \ + /* G006 */ "G006 (DCLS)" \ +} + +/** + * @brief Initializers for short RX timecode format name strings * * @note Must not be longer than 11 printable characters * * @see ::ICODE_RX_CODES */ -#define DEFAULT_ICODE_RX_NAMES_SHORT \ -{ \ - "B122/B123", \ - "A132/A133", \ - "B002/B003", \ - "A002/A003", \ - "AFNOR NF S", \ - "AFNOR DC", \ - "IEEE1344", \ - "IEEE1344 DC", \ - "B126/B127", \ - "B006/B007", \ - "G142/G146", \ - "G002/G006", \ - "C37.118", \ - "C37.118 DC", \ - "TXC-101", \ - "TXC-101 DC", \ - "E112", \ - "E002 DC", \ - "NASA-36", \ - "NASA-36 DC" \ -} - - -/** - * @brief Initializers for English format description strings +#define DEFAULT_ICODE_RX_NAMES_SHORT \ +{ \ + /* B122_B123 */ "B122/B123", \ + /* A132_A133 */ "A132/A133", \ + /* B002_B003 */ "B002/B003", \ + /* A002_A003 */ "A002/A003", \ + /* AFNOR */ "AFNOR NF S", \ + /* AFNOR_DC */ "AFNOR DC", \ + /* IEEE1344 */ "IEEE1344", \ + /* IEEE1344_DC */ "IEEE1344 DC", \ + /* B126_B127 */ "B126/B127", \ + /* B006_B007 */ "B006/B007", \ + /* G142 */ "G142", \ + /* G002 */ "G002 DC", \ + /* C37118 */ "C37.118", \ + /* C37118_DC */ "C37.118 DC", \ + /* TXC101 */ "TXC-101", \ + /* TXC101_DC */ "TXC-101 DC", \ + /* E112 */ "E112", \ + /* E002 */ "E002 DC", \ + /* NASA36 */ "NASA-36", \ + /* NASA36_DC */ "NASA-36 DC", \ + /* A136_A137 */ "A136/A137", \ + /* A006_A007 */ "A006/A007", \ + /* G146 */ "G146", \ + /* G006 */ "G006 DC" \ +} + + +/** + * @brief Initializers for English RX format description strings * * @see ::ICODE_RX_CODES */ -#define DEFAULT_ICODE_RX_DESCRIPTIONS_ENG \ -{ \ - "100 bps, 1 kHz carrier, SBS optionally", \ - "1000 bps, 10 kHz carrier, SBS optionally", \ - "100 bps, DCLS, SBS optionally", \ - "1000 bps, DCLS, SBS optionally", \ - "100 bps, 1 kHz carrier, SBS, complete date", \ - "100 bps, DCLS, SBS, complete date", \ - "100 bps, 1 kHz carrier, SBS, time zone info", \ - "100 bps, DCLS, SBS, time zone info", \ - "100 bps, 1 kHz carrier, complete date, SBS optionally", \ - "100 bps, DCLS, complete date, SBS optionally", \ - "10 kbps, 100 kHz carrier, complete date optionally", \ - "10 kbps, DCLS, complete date optionally", \ - "like IEEE1344, but UTC offset with reversed sign", \ - "like IEEE1344 DC, but UTC offset with reversed sign", \ - "code from TV time sync device TXC-101 DTR-6", \ - "DC code from TV time sync device TXC-101 DTR-6", \ - "10 bps, 100 Hz carrier", \ - "10 bps, DCLS", \ - "100 bps, 1 kHz carrier", \ - "100 bps, DCLS" \ -} - -/** - * @brief Bit masks used with ::IRIG_INFO::supp_codes +#define DEFAULT_ICODE_RX_DESCRIPTIONS_ENG \ +{ \ + /* B122_B123 */ "100 bps, 1 kHz carrier, SBS optionally", \ + /* A132_A133 */ "1000 bps, 10 kHz carrier, SBS optionally", \ + /* B002_B003 */ "100 bps, DCLS, SBS optionally", \ + /* A002_A003 */ "1000 bps, DCLS, SBS optionally", \ + /* AFNOR */ "100 bps, 1 kHz carrier, complete date, SBS", \ + /* AFNOR_DC */ "100 bps, DCLS, complete date, SBS", \ + /* IEEE1344 */ "100 bps, 1 kHz carrier, SBS, time zone info", \ + /* IEEE1344_DC */ "100 bps, DCLS, SBS, time zone info", \ + /* B126_B127 */ "100 bps, 1 kHz carrier, 2 digit year number, SBS optionally", \ + /* B006_B007 */ "100 bps, DCLS, 2 digit year number, SBS optionally", \ + /* G142 */ "10 kbps, 100 kHz carrier", \ + /* G002 */ "10 kbps, DCLS", \ + /* C37118 */ "like IEEE1344, but UTC offset with reversed sign", \ + /* C37118_DC */ "like IEEE1344 DC, but UTC offset with reversed sign", \ + /* TXC101 */ "code from TV time sync device TXC-101 DTR-6", \ + /* TXC101_DC */ "DC code from TV time sync device TXC-101 DTR-6", \ + /* E112 */ "10 bps, 100 Hz carrier", \ + /* E002 */ "10 bps, DCLS", \ + /* NASA36 */ "100 bps, 1 kHz carrier", \ + /* NASA36_DC */ "100 bps, DCLS", \ + /* A136_A137 */ "1000 bps, 10 kHz carrier, 2 digit year number, SBS optionally", \ + /* A006_A007 */ "1000 bps, DCLS, 2 digit year number, SBS optionally", \ + /* G146 */ "10 kbps, 100 kHz carrier, 2 digit year number", \ + /* G006 */ "10 kbps, DCLS, 2 digit year number" \ +} + +/** + * @brief Bit masks used with ::IRIG_INFO::supp_codes for RX * * These bit masks are used with timecode receivers only * @@ -3713,8 +5037,8 @@ enum ICODE_RX_CODES #define MSK_ICODE_RX_IEEE1344_DC ( 1UL << ICODE_RX_IEEE1344_DC ) #define MSK_ICODE_RX_B126_B127 ( 1UL << ICODE_RX_B126_B127 ) #define MSK_ICODE_RX_B006_B007 ( 1UL << ICODE_RX_B006_B007 ) -#define MSK_ICODE_RX_G142_G146 ( 1UL << ICODE_RX_G142_G146 ) -#define MSK_ICODE_RX_G002_G006 ( 1UL << ICODE_RX_G002_G006 ) +#define MSK_ICODE_RX_G142 ( 1UL << ICODE_RX_G142 ) +#define MSK_ICODE_RX_G002 ( 1UL << ICODE_RX_G002 ) #define MSK_ICODE_RX_C37118 ( 1UL << ICODE_RX_C37118 ) #define MSK_ICODE_RX_C37118_DC ( 1UL << ICODE_RX_C37118_DC ) #define MSK_ICODE_RX_TXC101 ( 1UL << ICODE_RX_TXC101 ) @@ -3723,12 +5047,16 @@ enum ICODE_RX_CODES #define MSK_ICODE_RX_E002 ( 1UL << ICODE_RX_E002 ) #define MSK_ICODE_RX_NASA36 ( 1UL << ICODE_RX_NASA36 ) #define MSK_ICODE_RX_NASA36_DC ( 1UL << ICODE_RX_NASA36_DC ) +#define MSK_ICODE_RX_A136_A137 ( 1UL << ICODE_RX_A136_A137 ) +#define MSK_ICODE_RX_A006_A007 ( 1UL << ICODE_RX_A006_A007 ) +#define MSK_ICODE_RX_G146 ( 1UL << ICODE_RX_G146 ) +#define MSK_ICODE_RX_G006 ( 1UL << ICODE_RX_G006 ) /** @} anchor ICODE_RX_MASKS */ /** - * @brief A mask of IRIG DCLS formats + * @brief A mask of IRIG RX DCLS formats */ #define MSK_ICODE_RX_DC \ ( \ @@ -3737,24 +5065,25 @@ enum ICODE_RX_CODES MSK_ICODE_RX_AFNOR_DC | \ MSK_ICODE_RX_IEEE1344_DC | \ MSK_ICODE_RX_B006_B007 | \ - MSK_ICODE_RX_G002_G006 | \ + MSK_ICODE_RX_G002 | \ MSK_ICODE_RX_C37118_DC | \ MSK_ICODE_RX_TXC101_DC | \ MSK_ICODE_RX_E002 | \ - MSK_ICODE_RX_NASA36_DC \ + MSK_ICODE_RX_NASA36_DC | \ + MSK_ICODE_RX_A006_A007 | \ + MSK_ICODE_RX_G006 \ ) /** - * @brief A mask of IRIG formats with 100 Hz carrier + * @brief A mask of IRIG RX formats with 100 Hz carrier */ #define MSK_ICODE_RX_100HZ \ ( \ - MSK_ICODE_RX_E112 | \ - MSK_ICODE_RX_E002 \ + MSK_ICODE_RX_E112 \ ) /** - * @brief A mask of IRIG formats with 1 kHz carrier + * @brief A mask of IRIG RX formats with 1 kHz carrier */ #define MSK_ICODE_RX_1KHZ \ ( \ @@ -3768,23 +5097,25 @@ enum ICODE_RX_CODES ) /** - * @brief A mask of IRIG formats with 10 kHz carrier + * @brief A mask of IRIG RX formats with 10 kHz carrier */ #define MSK_ICODE_RX_10KHZ \ ( \ - MSK_ICODE_RX_A132_A133 \ + MSK_ICODE_RX_A132_A133 | \ + MSK_ICODE_RX_A136_A137 \ ) /** - * @brief A mask of IRIG formats with 100 kHz carrier + * @brief A mask of IRIG RX formats with 100 kHz carrier */ #define MSK_ICODE_RX_100KHZ \ ( \ - MSK_ICODE_RX_G142_G146 \ + MSK_ICODE_RX_G142 | \ + MSK_ICODE_RX_G146 \ ) /** - * @brief A mask of IRIG formats with 10 bps data rate + * @brief A mask of IRIG RX formats with 10 bps data rate */ #define MSK_ICODE_RX_10BPS \ ( \ @@ -3793,7 +5124,7 @@ enum ICODE_RX_CODES ) /** - * @brief A mask of IRIG formats with 100 bps data rate + * @brief A mask of IRIG RX formats with 100 bps data rate */ #define MSK_ICODE_RX_100BPS \ ( \ @@ -3814,60 +5145,110 @@ enum ICODE_RX_CODES ) /** - * @brief A mask of IRIG formats with 1000 bps data rate + * @brief A mask of IRIG RX formats with 1000 bps data rate */ #define MSK_ICODE_RX_1000BPS \ ( \ MSK_ICODE_RX_A132_A133 | \ - MSK_ICODE_RX_A002_A003 \ + MSK_ICODE_RX_A002_A003 | \ + MSK_ICODE_RX_A136_A137 | \ + MSK_ICODE_RX_A006_A007 \ ) /** - * @brief A mask of IRIG formats with 10 kbps data rate + * @brief A mask of IRIG RX formats with 10 kbps data rate */ #define MSK_ICODE_RX_10000BPS \ ( \ - MSK_ICODE_RX_G142_G146 | \ - MSK_ICODE_RX_G002_G006 \ + MSK_ICODE_RX_G142 | \ + MSK_ICODE_RX_G002 | \ + MSK_ICODE_RX_G146 | \ + MSK_ICODE_RX_G006 \ ) /** - * @brief A mask of IRIG formats supporting 10ths of seconds + * @brief A mask of IRIG RX formats supporting 10ths of seconds */ #define MSK_ICODE_RX_HAS_SEC10THS \ ( \ MSK_ICODE_RX_A132_A133 | \ MSK_ICODE_RX_A002_A003 | \ - MSK_ICODE_RX_G142_G146 | \ - MSK_ICODE_RX_G002_G006 \ + MSK_ICODE_RX_G142 | \ + MSK_ICODE_RX_G002 | \ + MSK_ICODE_RX_A136_A137 | \ + MSK_ICODE_RX_A006_A007 | \ + MSK_ICODE_RX_G146 | \ + MSK_ICODE_RX_G006 \ ) /** - * @brief A mask of IRIG formats which support 100ths of seconds + * @brief A mask of IRIG RX formats which support 100ths of seconds */ #define MSK_ICODE_RX_HAS_SEC100THS \ ( \ - MSK_ICODE_RX_G142_G146 | \ - MSK_ICODE_RX_G002_G006 \ + MSK_ICODE_RX_G142 | \ + MSK_ICODE_RX_G002 | \ + MSK_ICODE_RX_G146 | \ + MSK_ICODE_RX_G006 \ ) /** - * @brief A mask of IRIG formats supporting a 2 digit year number + * @brief A mask of IRIG RX formats supporting a 2 digit year number after P5 + * + * Note: This macro specifies ONLY the codes where the year number + * is transmitted after position identifier P5. + * + * @see ::MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P6 + * @see ::MSK_ICODE_RX_HAS_ANY_SHORT_YEAR */ -#define MSK_ICODE_RX_HAS_SHORT_YEAR \ -( \ - MSK_ICODE_RX_AFNOR | \ - MSK_ICODE_RX_AFNOR_DC | \ - MSK_ICODE_RX_IEEE1344 | \ - MSK_ICODE_RX_IEEE1344_DC | \ - MSK_ICODE_RX_B126_B127 | \ - MSK_ICODE_RX_B006_B007 | \ - MSK_ICODE_RX_C37118 | \ - MSK_ICODE_RX_C37118_DC \ +#define MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P5 \ +( \ + MSK_ICODE_RX_AFNOR | \ + MSK_ICODE_RX_AFNOR_DC | \ + MSK_ICODE_RX_IEEE1344 | \ + MSK_ICODE_RX_IEEE1344_DC | \ + MSK_ICODE_RX_B126_B127 | \ + MSK_ICODE_RX_B006_B007 | \ + MSK_ICODE_RX_C37118 | \ + MSK_ICODE_RX_C37118_DC | \ + MSK_ICODE_RX_A136_A137 | \ + MSK_ICODE_RX_A006_A007 \ +) + +/** + * @brief A mask of IRIG RX formats supporting a 2 digit year number after P6 + * + * Note: This macro specifies ONLY the codes where the year number + * is transmitted after position identifier P6. + * + * @see ::MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P5 + * @see ::MSK_ICODE_RX_HAS_ANY_SHORT_YEAR + */ +#define MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P6 \ +( \ + MSK_ICODE_RX_G146 | \ + MSK_ICODE_RX_G006 \ +) + +/** + * @brief A mask of IRIG RX formats providing any 2 digit year number + * + * Note: Different sets of code frames may provide a year number + * in different locations of the transmitted code. + * + * @see ::MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P5 + * @see ::MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P6 + */ +#define MSK_ICODE_RX_HAS_ANY_SHORT_YEAR \ +( \ + MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P5 | \ + MSK_ICODE_RX_HAS_SHORT_YEAR_AFTER_P6 \ ) + + /** - * @brief A mask of IRIG formats supporting TFOM time quality indicator + * @brief A mask of IRIG RX formats supporting TFOM time quality indicator */ #define MSK_ICODE_RX_HAS_TFOM \ ( \ @@ -3878,7 +5259,7 @@ enum ICODE_RX_CODES ) /** - * @brief A mask of IRIG formats supporting CTQ continuous time quality + * @brief A mask of IRIG RX formats supporting CTQ continuous time quality * * This has been introduced in IEEE C37.118.1-2011 */ @@ -3891,7 +5272,7 @@ enum ICODE_RX_CODES ) /** - * @brief A mask of IRIG formats supporting time zone information + * @brief A mask of IRIG RX formats supporting time zone information */ #define MSK_ICODE_RX_HAS_TZI \ ( \ @@ -3902,11 +5283,11 @@ enum ICODE_RX_CODES ) /** - * @brief IRIG formats where UTC offset must be subtracted to yield UTC + * @brief IRIG RX formats where %UTC offset must be subtracted to yield %UTC * - * A mask of IRIG formats where the decoded UTC offset must be - * subtracted from the time decoded from the IRIG signal to yield UTC, e.g.:<br> - * (IRIG time 14:43:27 h) - (offs -6 h) = (UTC 20:43:27) + * A mask of IRIG formats where the decoded %UTC offset must be + * subtracted from the time decoded from the IRIG signal to yield %UTC, e.g.:<br> + * (IRIG time 14:43:27 h) - (offs -6 h) = (%UTC 20:43:27) */ #define MSK_ICODE_RX_UTC_OFFS_SUB \ ( \ @@ -3915,11 +5296,11 @@ enum ICODE_RX_CODES ) /** - * @brief IRIG formats where UTC offset must be added to yield UTC + * @brief IRIG RX formats where %UTC offset must be added to yield %UTC * - * A mask of IRIG formats where the decoded UTC offset must be - * added to the time decoded from the IRIG signal to yield UTC, e.g.:<br> - * (IRIG time 14:43:27 h) + (offs -6 h) = (UTC 08:43:27) + * A mask of IRIG formats where the decoded %UTC offset must be + * added to the time decoded from the IRIG signal to yield %UTC, e.g.:<br> + * (IRIG time 14:43:27 h) + (offs -6 h) = (%UTC 08:43:27) */ #define MSK_ICODE_RX_UTC_OFFS_ADD \ ( \ @@ -3928,7 +5309,7 @@ enum ICODE_RX_CODES ) /** - * @brief A mask of IRIG formats supporting a day of week number + * @brief A mask of IRIG RX formats supporting a day of week number */ #define MSK_ICODE_RX_HAS_AFNOR_WDAY \ ( \ @@ -3937,7 +5318,7 @@ enum ICODE_RX_CODES ) /** - * @brief A mask of IRIG formats supporting a date (day-of-month, month) + * @brief A mask of IRIG RX formats supporting a date (day-of-month, month) */ #define MSK_ICODE_RX_HAS_AFNOR_DATE \ ( \ @@ -3947,7 +5328,7 @@ enum ICODE_RX_CODES /** - * @brief The default mask of IRIG formats supported by IRIG receivers + * @brief The default mask of IRIG RX formats supported by IRIG receivers * * @note The formats which are actually supported should be retrieved * from the device @@ -3976,15 +5357,16 @@ enum ICODE_RX_CODES typedef struct { uint16_t icode; ///< IRIG signal code, see ::ICODE_RX_CODES and ::ICODE_TX_CODES - uint16_t flags; ///< see ::IFLAGS_BIT_MASKS + uint16_t flags; ///< See ::IFLAGS_BIT_MASKS } IRIG_SETTINGS; #define _mbg_swab_irig_settings( _p ) \ +do \ { \ _mbg_swab16( &(_p)->icode ); \ _mbg_swab16( &(_p)->flags ); \ -} +} while ( 0 ) @@ -4014,8 +5396,8 @@ enum IFLAGS_BITS */ enum IFLAGS_BIT_MASKS { - IFLAGS_DISABLE_TFOM = ( 1UL << IFLAGS_BIT_DISABLE_TFOM ), ///< see ::IFLAGS_BIT_DISABLE_TFOM - IFLAGS_TX_GEN_LOCAL_TIME = ( 1UL << IFLAGS_BIT_TX_GEN_LOCAL_TIME ), ///< see ::IFLAGS_BIT_TX_GEN_LOCAL_TIME + IFLAGS_DISABLE_TFOM = ( 1UL << IFLAGS_BIT_DISABLE_TFOM ), ///< See ::IFLAGS_BIT_DISABLE_TFOM + IFLAGS_TX_GEN_LOCAL_TIME = ( 1UL << IFLAGS_BIT_TX_GEN_LOCAL_TIME ), ///< See ::IFLAGS_BIT_TX_GEN_LOCAL_TIME IFLAGS_MASK = ( ( 1UL << N_IFLAGS_BITS ) - 1 ) ///< mask of all known flags }; @@ -4035,10 +5417,11 @@ typedef struct } IRIG_INFO; #define _mbg_swab_irig_info( _p ) \ +do \ { \ _mbg_swab_irig_settings( &(_p)->settings ); \ _mbg_swab32( &(_p)->supp_codes ); \ -} +} while ( 0 ) /** @@ -4074,11 +5457,12 @@ typedef struct } IRIG_RX_COMP; #define _mbg_swab_irig_rx_comp( _p ) \ +do \ { \ int i; \ for ( i = 0; i < N_IRIG_RX_COMP_VAL; i++ ) \ _mbg_swab16( &(_p)->c[i] ); \ -} +} while ( 0 ) /** The absolute value of the maximum compensation value accepted by a device */ @@ -4091,16 +5475,17 @@ typedef struct */ typedef struct { - uint16_t type; ///< record type, see ::CAL_REC_TYPES - uint16_t idx; ///< index if several records of same type are supported, see ::IRIG_RX_COMP_GROUPS + uint16_t type; ///< Record type, see ::CAL_REC_TYPES + uint16_t idx; ///< Index if several records of same type are supported, see ::IRIG_RX_COMP_GROUPS } CAL_REC_HDR; #define _mbg_swab_cal_rec_hdr( _p ) \ +do \ { \ _mbg_swab16( &(_p)->type ); \ _mbg_swab16( &(_p)->idx ); \ -} +} while ( 0 ) /** @@ -4157,17 +5542,18 @@ typedef struct } CAL_REC_IRIG_RX_COMP; #define _mbg_swab_cal_rec_irig_rx_comp( _p ) \ +do \ { \ _mbg_swab_cal_rec_hdr( &(_p)->hdr ); \ _mbg_swab_irig_rx_comp( &(_p)->comp_data ); \ -} +} while ( 0 ) /** @} defgroup group_irig_comp */ /** - * @brief A data type used to read the board's debug status + * @brief A data type used to read the debug status of the device. * * @note This also includes IRIG decoder status. * @@ -4263,7 +5649,7 @@ enum MBG_DEBUG_STATUS_BITS * @note There's a special flag ::MBG_REF_OFFS_NOT_CFGD indicating that * this parameter is unconfigured, in which case a Meinberg time code * receiver refuses to synchronize to the time code signal unless a time - * code frame has been configured which provides the UTC offset (namely + * code frame has been configured which provides the %UTC offset (namely * IEEE 1344 or IEEE C37.118). */ typedef int16_t MBG_REF_OFFS; @@ -4283,7 +5669,7 @@ typedef int16_t MBG_REF_OFFS; * (time offset from %UTC) has not yet been configured. This is usually * the case for IRIG receiver devices right after they have been shipped. */ -#define MBG_REF_OFFS_NOT_CFGD 0x8000 +#define MBG_REF_OFFS_NOT_CFGD ( (MBG_REF_OFFS) 0x8000 ) @@ -4299,9 +5685,10 @@ typedef struct } MBG_OPT_SETTINGS; #define _mbg_swab_mbg_opt_settings( _p ) \ +do \ { \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) /** @@ -4318,10 +5705,11 @@ typedef struct } MBG_OPT_INFO; #define _mbg_swab_mbg_opt_info( _p ) \ +do \ { \ _mbg_swab_mbg_opt_settings( &(_p)->settings ); \ _mbg_swab32( &(_p)->supp_flags ); \ -} +} while ( 0 ) /** @@ -4342,8 +5730,8 @@ enum MBG_OPT_BITS */ enum MBG_OPT_FLAGS { - MBG_OPT_FLAG_STR_UTC = ( 1UL << MBG_OPT_BIT_STR_UTC ), ///< see ::MBG_OPT_BIT_STR_UTC - MBG_OPT_FLAG_EMU_SYNC = ( 1UL << MBG_OPT_BIT_EMU_SYNC ) ///< see ::MBG_OPT_BIT_EMU_SYNC + MBG_OPT_FLAG_STR_UTC = ( 1UL << MBG_OPT_BIT_STR_UTC ), ///< See ::MBG_OPT_BIT_STR_UTC + MBG_OPT_FLAG_EMU_SYNC = ( 1UL << MBG_OPT_BIT_EMU_SYNC ) ///< See ::MBG_OPT_BIT_EMU_SYNC }; @@ -4418,7 +5806,7 @@ typedef struct /** * @defgroup group_time_scale Time Scale Configuration * - * Used to configure the GPS receiver's basic time scale. + * Used to configure the basic time scale of the GPS receiver. * By default this is %UTC which can optionally be converted * to some local time. However, some applications prefer * TAI or pure GPS time. This can be configured using the @@ -4449,9 +5837,9 @@ enum MBG_TIME_SCALES */ enum MBG_TIME_SCALE_MASKS { - MBG_TIME_SCALE_MSK_DEFAULT = ( 1UL << MBG_TIME_SCALE_DEFAULT ), ///< see ::MBG_TIME_SCALE_DEFAULT - MBG_TIME_SCALE_MSK_GPS = ( 1UL << MBG_TIME_SCALE_GPS ), ///< see ::MBG_TIME_SCALE_GPS - MBG_TIME_SCALE_MSK_TAI = ( 1UL << MBG_TIME_SCALE_TAI ) ///< see ::MBG_TIME_SCALE_TAI + MBG_TIME_SCALE_MSK_DEFAULT = ( 1UL << MBG_TIME_SCALE_DEFAULT ), ///< See ::MBG_TIME_SCALE_DEFAULT + MBG_TIME_SCALE_MSK_GPS = ( 1UL << MBG_TIME_SCALE_GPS ), ///< See ::MBG_TIME_SCALE_GPS + MBG_TIME_SCALE_MSK_TAI = ( 1UL << MBG_TIME_SCALE_TAI ) ///< See ::MBG_TIME_SCALE_TAI }; #define MBG_TIME_SCALE_STRS \ @@ -4495,21 +5883,27 @@ typedef struct } MBG_TIME_SCALE_INFO; #define _mbg_swab_mbg_time_scale_info( _p ) \ +do \ { \ _mbg_swab_mbg_time_scale_settings( &(_p)->settings ); \ _mbg_swab_mbg_time_scale_settings( &(_p)->max_settings ); \ _mbg_swab32( &(_p)->supp_scales ); \ -} +} while ( 0 ) /** @} defgroup group_time_scale */ -/* - * The structures below are required to setup the programmable + +/** + * @defgroup group_pout_api Programmable Output API + * + * These structures below are used to configure the programmable * pulse outputs which are provided by some GPS receivers. * The number of programmable pulse outputs supported by a GPS - * receiver is reported in the RECEIVER_INFO::n_str_type field. - */ + * receiver is reported in the RECEIVER_INFO::n_prg_out field. + * + * @{ */ + /** * @brief A calendar date including full year number @@ -4523,9 +5917,10 @@ typedef struct } MBG_DATE; #define _mbg_swab_mbg_date( _p ) \ +do \ { \ _mbg_swab16( &(_p)->year ); \ -} +} while ( 0 ) /** @@ -4536,7 +5931,7 @@ typedef struct uint8_t hour; ///< 0..23 uint8_t min; ///< 0..59 uint8_t sec; ///< 0..59,60 - uint8_t sec100; ///< reserved, currently always 0 + uint8_t sec100; ///< 100ths of seconds } MBG_TIME; @@ -4557,14 +5952,20 @@ typedef struct } MBG_DATE_TIME; #define _mbg_swab_mbg_date_time( _p ) \ +do \ { \ _mbg_swab_mbg_date( &(_p)->d ); \ _mbg_swab_mbg_time( &(_p)->t ); \ -} +} while ( 0 ) /** * @brief A structure to define on/off cycle times + * + * @note Eventually the ::MBG_TIME::sec100 fields in + * ::POUT_TIME:on and ::POUT_TIME:off are not evaluated + * by the firmware in ::POUT_TIMER mode, and thus + * should be set to 0 for this mode. */ typedef struct { @@ -4574,10 +5975,12 @@ typedef struct } POUT_TIME; #define _mbg_swab_pout_time( _p ) \ +do \ { \ _mbg_swab_mbg_date_time( &(_p)->on ); \ _mbg_swab_mbg_date_time( &(_p)->off ); \ -} +} while ( 0 ) + /** @@ -4588,78 +5991,106 @@ typedef struct #define N_POUT_TIMES 3 /** - * @brief Configuration settings for a single programmable pulse output + * @brief A Generic data field for programmable output settings */ -typedef struct +typedef union { - uint16_t mode; ///< mode of operation, see ::POUT_MODES - uint16_t mode_param; ///< depending on the mode, e.g. pulse length, or index of a signal source - uint16_t timeout; ///< timeout after which output signal is disabled [min], used with ::POUT_DCF77 and ::POUT_DCF77_M59 only, see ::MAX_POUT_DCF_TIMOUT - uint16_t flags; ///< @see ::POUT_SETTINGS_FLAGS - POUT_TIME tm[N_POUT_TIMES]; ///< switching times, or other data, see ::POUT_DATA + /// Switching times. See ::POUT_MODES_DATA_TM, ::POUT_MODES_DATA_TM_0 + POUT_TIME tm[N_POUT_TIMES]; + + uint8_t b[N_POUT_TIMES * sizeof( POUT_TIME )]; + + /// Only if ::POUT_SUPP_PULSE_SHIFT is set, this field can be used to + /// configure the time interval in [ns] by which output pulse slopes are + /// to be shifted. The configured pulse shift must be in the range + /// ::DEFAULT_POUT_PULSE_SHIFT_MIN through ::DEFAULT_POUT_PULSE_SHIFT_MAX. + /// The resolution / steps at which the pulse shift interval can be configured + /// is returned in ::POUT_INFO::pulse_shift_res. + /// @see ::POUT_MODES_DATA_PULSE_SHIFT + int32_t pulse_shift; + +} POUT_DATA; + +#define DEFAULT_POUT_PULSE_SHIFT_MIN -500000000L ///< Default minimum value for ::POUT_DATA::pulse_shift, in [ns] +#define DEFAULT_POUT_PULSE_SHIFT_MAX 499000000L ///< Default maximum value for ::POUT_DATA::pulse_shift, in [ns] -} POUT_SETTINGS; /** - * @brief A Generic data field for programmable output settings + * @brief Convert ::POUT_DATA endianess depending on the mode * - * If the mode is set to ::POUT_TIME_SLOTS then ::POUT_SETTINGS::tm must be - * interpreted as ::POUT_DATA, i.e. just an array of bytes. We can not change - * the type of the tm field to a union for compatibility reasons ... :( + * Assuming the mode is passed to the macro with correct endianess. */ -typedef union +#define _mbg_swab_pout_data( _p, _mode ) \ +do \ +{ \ + uint32_t mode_mask = 1UL << _mode; \ + \ + if ( mode_mask & POUT_MODES_DATA_TM ) \ + { \ + int i; \ + \ + for ( i = 0; i < N_POUT_TIMES; i++ ) \ + _mbg_swab_pout_time( &(_p)->tm[i] ); \ + } \ + else \ + { \ + if ( mode_mask & POUT_MODES_DATA_TM_0 ) \ + _mbg_swab_pout_time( &(_p)->tm[0] ); \ + else \ + if ( mode_mask & POUT_MODES_DATA_PULSE_SHIFT ) \ + _mbg_swab32( &(_p)->pulse_shift ); \ + } \ + \ +} while ( 0 ) + + + +/** + * @brief Configuration settings for a single programmable pulse output + */ +typedef struct { - uint8_t b[N_POUT_TIMES * sizeof( POUT_TIME )]; + uint16_t mode; ///< Mode of operation, see ::POUT_MODES + uint16_t mode_param; ///< Optional parameter depending on the mode, see @ref POUT_MODES_PARAM_MASKS -} POUT_DATA; + /// @brief Timeout [min] which can be specified for some modes, see ::POUT_MODES_TIMEOUT, ::MAX_POUT_DCF_TIMOUT. + /// + /// If the clock looses synchronization then the output + /// - is disabled ***immediately*** if ::POUT_IF_SYNC_ONLY is set in #flags + /// - is disabled after #timeout, if #timeout is not 0 (see ::MAX_POUT_DCF_TIMOUT) + /// - stays enabled if #timeout is 0 ***and*** ::POUT_IF_SYNC_ONLY is ***not*** set in #flags + uint16_t timeout; + + uint16_t flags; ///< @see ::POUT_SETTINGS_FLAGS + POUT_DATA pout_data; ///< Additional configuration data, see ::POUT_DATA +} POUT_SETTINGS; /** * @brief Convert ::POUT_SETTINGS endianess after reading from a device - * - * When reading data from a device we first need to correct the endianess - * of the mode first, and correct the endianess of the tm field only - * if the tm field is not interpreted as ::POUT_DATA. */ -#define _mbg_swab_pout_settings_on_get( _p ) \ -{ \ - _mbg_swab16( &(_p)->mode ); \ - _mbg_swab16( &(_p)->mode_param ); \ - _mbg_swab16( &(_p)->timeout ); \ - _mbg_swab16( &(_p)->flags ); \ - \ - if ( (_p)->mode != POUT_TIME_SLOTS ) \ - { \ - int i; \ - \ - for ( i = 0; i < N_POUT_TIMES; i++ ) \ - _mbg_swab_pout_time( &(_p)->tm[i] ); \ - } \ -} +#define _mbg_swab_pout_settings_on_get( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->mode ); \ + _mbg_swab16( &(_p)->mode_param ); \ + _mbg_swab16( &(_p)->timeout ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab_pout_data( &(_p)->pout_data, (_p)->mode ); \ +} while ( 0 ) /** * @brief Convert ::POUT_SETTINGS endianess before writing to a device - * - * When writing data to a device we first need to check the mode, - * and correct the endianess of the tm field only if the tm field - * is not interpreted as ::POUT_DATA. Finally we can also correct - * the endianess of the mode field. */ -#define _mbg_swab_pout_settings_on_set( _p ) \ -{ \ - if ( (_p)->mode != POUT_TIME_SLOTS ) \ - { \ - int i; \ - \ - for ( i = 0; i < N_POUT_TIMES; i++ ) \ - _mbg_swab_pout_time( &(_p)->tm[i] ); \ - } \ - \ - _mbg_swab16( &(_p)->mode ); \ - _mbg_swab16( &(_p)->mode_param ); \ - _mbg_swab16( &(_p)->timeout ); \ - _mbg_swab16( &(_p)->flags ); \ -} +#define _mbg_swab_pout_settings_on_set( _p ) \ +do \ +{ \ + _mbg_swab_pout_data( &(_p)->pout_data, (_p)->mode ); \ + _mbg_swab16( &(_p)->mode ); \ + _mbg_swab16( &(_p)->mode_param ); \ + _mbg_swab16( &(_p)->timeout ); \ + _mbg_swab16( &(_p)->flags ); \ +} while ( 0 ) @@ -4670,6 +6101,7 @@ typedef union * of time slots per minute is stored in ::POUT_SETTINGS::mode_param. * Valid numbers are all numbers n in the range ::MIN_TIME_SLOTS_PER_MINUTE * to ::MAX_TIME_SLOTS_PER_MINUTE for which the remainder of 60 / n is 0. + * @see ::POUT_MODES_MODE_PARAM_AS_SLOTS_PER_MIN * * @anchor POUT_TIME_SLOTS_MODE_DEFS @{ */ @@ -4703,7 +6135,7 @@ typedef union * * These codes are used with ::POUT_SETTINGS::mode. One or more of * the remaining fields in ::POUT_SETTINGS are evaluated depending - * on the selected mode. + * on the selected mode. Unused fields should be set to 0. * * Unless ::POUT_NOT_INVERTIBLE is set in ::POUT_INFO::flags * the output signal level can be inverted if ::POUT_INVERTED @@ -4712,30 +6144,108 @@ typedef union * @note Not every programmable pulse output supports all modes. * * @see @ref POUT_MODE_MASKS + * @see @ref POUT_MODES_PARAM_MASKS + * @see @ref ENG_POUT_NAMES + * @see @ref ENG_POUT_HINTS */ enum POUT_MODES { - POUT_IDLE, ///< always off, or on if ::POUT_INVERTED flag is set - POUT_TIMER, ///< switch on/off at times specified in ::POUT_SETTINGS::tm - POUT_SINGLE_SHOT, ///< pulse at time POUT_SETTINGS::tm[0].on, pulse length in ::POUT_SETTINGS::mode_param [10 ms units], see ::MAX_POUT_PULSE_LEN - POUT_CYCLIC_PULSE, ///< pulse every POUT_SETTINGS::tm[0].on.t interval, pulse length in ::POUT_SETTINGS::mode_param [10 ms units], see ::MAX_POUT_PULSE_LEN - POUT_PER_SEC, ///< pulse if second changes, pulse length in ::POUT_SETTINGS::mode_param [10 ms units], see ::MAX_POUT_PULSE_LEN - POUT_PER_MIN, ///< pulse if minute changes, pulse length in ::POUT_SETTINGS::mode_param [10 ms units], see ::MAX_POUT_PULSE_LEN - POUT_PER_HOUR, ///< pulse if hour changes, pulse length in ::POUT_SETTINGS::mode_param [10 ms units], see ::MAX_POUT_PULSE_LEN - POUT_DCF77, ///< emulate DCF77 signal, uses ::POUT_SETTINGS::timeout, see ::MAX_POUT_DCF_TIMOUT - POUT_POS_OK, ///< on if receiver position verified (nav_solved) - POUT_TIME_SYNC, ///< on if time synchronized (time_syn) - POUT_ALL_SYNC, ///< on if position verified and time synchronized - POUT_TIMECODE, ///< IRIG/AFNOR DCLS signal output - POUT_TIMESTR, ///< serial time string, ::POUT_SETTINGS::mode_param contains the number of the COM port, see ::MAX_POUT_TIMESTR_PORTS - POUT_10MHZ, ///< 10 MHz fixed frequency - POUT_DCF77_M59, ///< DCF77-like signal with 500 ms pulse in 59th second, uses ::POUT_SETTINGS::timeout, see ::MAX_POUT_DCF_TIMOUT - POUT_SYNTH, ///< programmable frequency synthesizer output signal - POUT_TIME_SLOTS, ///< programmable time slots during each minute, uses ::POUT_DATA, ::POUT_SETTINGS::mode_param contains time slots per minute - POUT_GPIO, ///< GPIO input or output signal, ::POUT_SETTINGS::mode_param specifies the GPIO number, see ::MBG_GPIO_CFG_LIMITS::num_io - // New modes have to be added here at the end of the enumeration, and - // the POUT_MODE_MASKS and string initializers (also in pcpslstr.h) - // have to be updated accordingly. + /// Output is normally always 'off', or always 'on' in case + /// flag ::POUT_INVERTED is set in ::POUT_SETTINGS::flags. + POUT_IDLE, + + /// Switch 'on' or 'off' at the times specified in ::POUT_DATA::tm. + /// + /// @note Eventually the ::MBG_TIME::sec100 fields in + /// ::POUT_TIME:on and ::POUT_TIME:off are not evaluated + /// by the firmware in ::POUT_TIMER mode, and thus + /// should be always set to 0 in this mode. + POUT_TIMER, + + /// Generate a pulse at the time specified in the tm[0].on field + /// in ::POUT_SETTINGS::pout_data. + /// Pulse length as specified in ::POUT_SETTINGS::mode_param, + /// in [10 ms] units. + /// See ::MAX_POUT_PULSE_LEN. + POUT_SINGLE_SHOT, + + /// Generate a cyclic pulse at the time specified in the tm[0].on.t + /// field in ::POUT_SETTINGS::pout_data. + /// Pulse length as specified in ::POUT_SETTINGS::mode_param, + /// in [10 ms] units. + /// See ::MAX_POUT_PULSE_LEN. + POUT_CYCLIC_PULSE, + + /// Generate a pulse whenever the second changes. + /// Pulse length as specified in ::POUT_SETTINGS::mode_param, + /// in [10 ms] units. + /// See ::MAX_POUT_PULSE_LEN. + POUT_PER_SEC, + + /// Generate a pulse whenever the minute changes. + /// Pulse length as specified in ::POUT_SETTINGS::mode_param, + /// in [10 ms] units. + /// See ::MAX_POUT_PULSE_LEN. + POUT_PER_MIN, + + /// Generate a pulse whenever the hour changes. + /// Pulse length as specified in ::POUT_SETTINGS::mode_param, + /// in [10 ms] units. + /// See ::MAX_POUT_PULSE_LEN. + POUT_PER_HOUR, + + /// Generate DCF77-compatible second marks. + /// Pulse length according to the DCF77 specifications. + /// See ::POUT_DCF77_M59, ::POUT_SETTINGS::timeout and ::MAX_POUT_DCF_TIMOUT. + POUT_DCF77, + + /// Output switched on if receiver position verified (condition nav_solved). + POUT_POS_OK, + + /// Output switched on if time synchronized (condition time_syn). + POUT_TIME_SYNC, + + /// Output switched on if both position verified and time synchronized. + POUT_ALL_SYNC, + + /// IRIG/AFNOR DCLS time code signal mapped to this output. + POUT_TIMECODE, + + /// Serial time string of one one of the serial ports mapped to this output. + /// ::POUT_SETTINGS::mode_param contains the number of the COM port. + /// See ::MAX_POUT_TIMESTR_PORTS. + POUT_TIMESTR, + + /// 10 MHz fixed frequency output. + POUT_10MHZ, + + /// DCF77-like signal with extra 500 ms pulse in the 59th second + /// (the original DCF77 signal has no such pulse). See ::POUT_DCF77, + /// ::POUT_SETTINGS::timeout and ::MAX_POUT_DCF_TIMOUT. + POUT_DCF77_M59, + + /// Output signal generated by the programmable frequency synthesizer. + POUT_SYNTH, + + /// Programmable time slots during each minute. + /// ::POUT_SETTINGS::mode_param specifies the time slots per minute. + /// Uses ::POUT_DATA. ::TODO + POUT_TIME_SLOTS, + + /// A GPIO input or output signal is reflected at this pulse output. + /// ::POUT_SETTINGS::mode_param specifies the GPIO number which must + /// be in the range 0..::MBG_GPIO_CFG_LIMITS::num_io. + POUT_GPIO, + + /// A 1 PPS signal with a fixed 20 us pulse length + POUT_PTTI_PPS, + + /// A HaveQuick signal as configured in ::HAVEQUICK_SETTINGS::format + POUT_HAVEQUICK, + + // New modes have to be added here at the end of the enumeration, and the + // POUT_MODE_MASKS, the POUT_MODES_PARAM_MASKS as well as string initializers + // (also in pcpslstr.h) have to be updated accordingly. N_POUT_MODES ///< the number of known modes }; @@ -4750,32 +6260,185 @@ enum POUT_MODES * * @anchor POUT_MODE_MASKS @{ */ -#define MSK_POUT_IDLE ( 1UL << POUT_IDLE ) ///< see ::POUT_IDLE -#define MSK_POUT_TIMER ( 1UL << POUT_TIMER ) ///< see ::POUT_TIMER -#define MSK_POUT_SINGLE_SHOT ( 1UL << POUT_SINGLE_SHOT ) ///< see ::POUT_SINGLE_SHOT -#define MSK_POUT_CYCLIC_PULSE ( 1UL << POUT_CYCLIC_PULSE ) ///< see ::POUT_CYCLIC_PULSE -#define MSK_POUT_PER_SEC ( 1UL << POUT_PER_SEC ) ///< see ::POUT_PER_SEC -#define MSK_POUT_PER_MIN ( 1UL << POUT_PER_MIN ) ///< see ::POUT_PER_MIN -#define MSK_POUT_PER_HOUR ( 1UL << POUT_PER_HOUR ) ///< see ::POUT_PER_HOUR -#define MSK_POUT_DCF77 ( 1UL << POUT_DCF77 ) ///< see ::POUT_DCF77 -#define MSK_POUT_POS_OK ( 1UL << POUT_POS_OK ) ///< see ::POUT_POS_OK -#define MSK_POUT_TIME_SYNC ( 1UL << POUT_TIME_SYNC ) ///< see ::POUT_TIME_SYNC -#define MSK_POUT_ALL_SYNC ( 1UL << POUT_ALL_SYNC ) ///< see ::POUT_ALL_SYNC -#define MSK_POUT_TIMECODE ( 1UL << POUT_TIMECODE ) ///< see ::POUT_TIMECODE -#define MSK_POUT_TIMESTR ( 1UL << POUT_TIMESTR ) ///< see ::POUT_TIMESTR -#define MSK_POUT_10MHZ ( 1UL << POUT_10MHZ ) ///< see ::POUT_10MHZ -#define MSK_POUT_DCF77_M59 ( 1UL << POUT_DCF77_M59 ) ///< see ::POUT_DCF77_M59 -#define MSK_POUT_SYNTH ( 1UL << POUT_SYNTH ) ///< see ::POUT_SYNTH -#define MSK_POUT_TIME_SLOTS ( 1UL << POUT_TIME_SLOTS ) ///< see ::POUT_TIME_SLOTS -#define MSK_POUT_GPIO ( 1UL << POUT_GPIO ) ///< see ::POUT_GPIO +#define MSK_POUT_IDLE ( 1UL << POUT_IDLE ) ///< See ::POUT_IDLE +#define MSK_POUT_TIMER ( 1UL << POUT_TIMER ) ///< See ::POUT_TIMER +#define MSK_POUT_SINGLE_SHOT ( 1UL << POUT_SINGLE_SHOT ) ///< See ::POUT_SINGLE_SHOT +#define MSK_POUT_CYCLIC_PULSE ( 1UL << POUT_CYCLIC_PULSE ) ///< See ::POUT_CYCLIC_PULSE +#define MSK_POUT_PER_SEC ( 1UL << POUT_PER_SEC ) ///< See ::POUT_PER_SEC +#define MSK_POUT_PER_MIN ( 1UL << POUT_PER_MIN ) ///< See ::POUT_PER_MIN +#define MSK_POUT_PER_HOUR ( 1UL << POUT_PER_HOUR ) ///< See ::POUT_PER_HOUR +#define MSK_POUT_DCF77 ( 1UL << POUT_DCF77 ) ///< See ::POUT_DCF77 +#define MSK_POUT_POS_OK ( 1UL << POUT_POS_OK ) ///< See ::POUT_POS_OK +#define MSK_POUT_TIME_SYNC ( 1UL << POUT_TIME_SYNC ) ///< See ::POUT_TIME_SYNC +#define MSK_POUT_ALL_SYNC ( 1UL << POUT_ALL_SYNC ) ///< See ::POUT_ALL_SYNC +#define MSK_POUT_TIMECODE ( 1UL << POUT_TIMECODE ) ///< See ::POUT_TIMECODE +#define MSK_POUT_TIMESTR ( 1UL << POUT_TIMESTR ) ///< See ::POUT_TIMESTR +#define MSK_POUT_10MHZ ( 1UL << POUT_10MHZ ) ///< See ::POUT_10MHZ +#define MSK_POUT_DCF77_M59 ( 1UL << POUT_DCF77_M59 ) ///< See ::POUT_DCF77_M59 +#define MSK_POUT_SYNTH ( 1UL << POUT_SYNTH ) ///< See ::POUT_SYNTH +#define MSK_POUT_TIME_SLOTS ( 1UL << POUT_TIME_SLOTS ) ///< See ::POUT_TIME_SLOTS +#define MSK_POUT_GPIO ( 1UL << POUT_GPIO ) ///< See ::POUT_GPIO +#define MSK_POUT_PTTI_PPS ( 1UL << POUT_PTTI_PPS ) ///< See ::POUT_PTTI_PPS +#define MSK_POUT_HAVEQUICK ( 1UL << POUT_HAVEQUICK ) ///< See ::POUT_HAVEQUICK /** @} anchor POUT_MODE_MASKS */ -/* - * Default initializers for English pulse mode names. Initializers - * for multi-language strings can be found in pcpslstr.h. + +/** + * @brief Bit masks indicating which parameters relevant for which ::POUT_MODES + * + * @see ::POUT_MODES + * @see @ref POUT_MODE_MASKS + * + * @anchor POUT_MODES_PARAM_MASKS @{ */ + + +/** + * @brief POUT modes which use the full ::POUT_DATA::tm array as parameter */ +#define POUT_MODES_DATA_TM \ +( \ + MSK_POUT_TIMER \ +) + + +/** + * @brief POUT modes which use only ::POUT_DATA::tm[0] as parameter + */ +#define POUT_MODES_DATA_TM_0 \ +( \ + MSK_POUT_SINGLE_SHOT | \ + MSK_POUT_CYCLIC_PULSE \ +) + + +/** + * @brief POUT modes which use ::POUT_SETTINGS::mode_param as pulse length + * + * @see ::MAX_POUT_PULSE_LEN + */ +#define POUT_MODES_MODE_PARAM_AS_PULSE_LEN \ +( \ + MSK_POUT_SINGLE_SHOT | \ + MSK_POUT_CYCLIC_PULSE | \ + MSK_POUT_PER_SEC | \ + MSK_POUT_PER_MIN | \ + MSK_POUT_PER_HOUR \ +) + + +/** + * @brief POUT modes which use ::POUT_SETTINGS::mode_param as COM port index number + */ +#define POUT_MODES_MODE_PARAM_AS_COM_IDX \ +( \ + MSK_POUT_TIMESTR \ +) + + +/** + * @brief POUT modes which use ::POUT_SETTINGS::mode_param as time slots per minute + * + * @see @ref POUT_TIME_SLOTS_MODE_DEFS + */ +#define POUT_MODES_MODE_PARAM_AS_SLOTS_PER_MIN \ +( \ + MSK_POUT_TIME_SLOTS \ +) + + +/** + * @brief POUT modes which use ::POUT_SETTINGS::mode_param as GPIO index number + */ +#define POUT_MODES_MODE_PARAM_AS_GPIO_IDX \ +( \ + MSK_POUT_GPIO \ +) + + +/** + * @brief POUT modes which use ::POUT_SETTINGS::timeout + */ +#define POUT_MODES_TIMEOUT \ +( \ + MSK_POUT_DCF77 | \ + MSK_POUT_DCF77_M59 \ +) + + +/** + * @brief POUT modes which which support ::POUT_TIMEBASE_UTC + */ +#define POUT_MODES_SUPP_TIMEBASE_UTC \ +( \ + MSK_POUT_DCF77 | \ + MSK_POUT_DCF77_M59 \ +) + + +/** + * @brief POUT modes which use ::POUT_DATA::pulse_shift + * + * @note: Supported only if ::POUT_SUPP_PULSE_SHIFT is set + */ +#define POUT_MODES_DATA_PULSE_SHIFT \ +( \ + MSK_POUT_PER_SEC | \ + MSK_POUT_PER_MIN | \ + MSK_POUT_PER_HOUR \ +) + + +/** + * @brief POUT modes which support ::POUT_SUPP_IF_SYNC_ONLY + * + * Even if ::POUT_SUPP_IF_SYNC_ONLY is set in ::POUT_INFO::flags + * the associated flag ::POUT_IF_SYNC_ONLY in ::POUT_SETTINGS::flags + * may be evaluated depending on the mode. + * + * Modes ::POUT_POS_OK, ::POUT_TIME_SYNC, and ::MSK_POUT_ALL_SYNC + * are explicitly excluded. + * + * For modes ::MSK_POUT_DCF77 and ::MSK_POUT_DCF77_M59 see also + * ::POUT_SETTINGS::timeout. + */ +#define POUT_MODES_SUPP_IF_SYNC_ONLY \ +( \ + MSK_POUT_IDLE | \ + MSK_POUT_TIMER | \ + MSK_POUT_SINGLE_SHOT | \ + MSK_POUT_CYCLIC_PULSE | \ + MSK_POUT_PER_SEC | \ + MSK_POUT_PER_MIN | \ + MSK_POUT_PER_HOUR | \ + MSK_POUT_DCF77 | \ + MSK_POUT_TIMECODE | \ + MSK_POUT_TIMESTR | \ + MSK_POUT_10MHZ | \ + MSK_POUT_DCF77_M59 | \ + MSK_POUT_SYNTH | \ + MSK_POUT_TIME_SLOTS | \ + MSK_POUT_GPIO | \ + MSK_POUT_PTTI_PPS | \ + MSK_POUT_HAVEQUICK \ +) + +/** @} anchor POUT_MODES_PARAM_MASKS */ + + + +/** + * @brief Name strings associated with ::POUT_MODES + * + * Default initializers for English programmable output mode names. + * Initializers for multi-language strings can be found in pcpslstr.h. + * + * @see ::POUT_MODES + * @see ::DEFAULT_ENG_POUT_NAMES + * + * @anchor ENG_POUT_NAMES @{ */ + #define ENG_POUT_NAME_IDLE "Idle" #define ENG_POUT_NAME_TIMER "Timer" #define ENG_POUT_NAME_SINGLE_SHOT "Single Shot" @@ -4794,7 +6457,18 @@ enum POUT_MODES #define ENG_POUT_NAME_SYNTH "Synthesizer Frequency" #define ENG_POUT_NAME_TIME_SLOTS "Time Slots per Minute" #define ENG_POUT_NAME_GPIO "GPIO Signal" +#define ENG_POUT_PTTI_PPS "PTTI 1 PPS" +#define ENG_POUT_HAVEQUICK "HaveQuick" + +/** @} anchor ENG_POUT_NAMES */ + + +/** + * @brief An initializer for a table of English POUT name strings + * + * @see @ref ENG_POUT_NAMES + */ #define DEFAULT_ENG_POUT_NAMES \ { \ ENG_POUT_NAME_IDLE, \ @@ -4814,10 +6488,23 @@ enum POUT_MODES ENG_POUT_NAME_DCF77_M59, \ ENG_POUT_NAME_SYNTH, \ ENG_POUT_NAME_TIME_SLOTS, \ - ENG_POUT_NAME_GPIO \ + ENG_POUT_NAME_GPIO, \ + ENG_POUT_PTTI_PPS, \ + ENG_POUT_HAVEQUICK \ } +/** + * @brief Hint strings associated with ::POUT_MODES + * + * Default initializers for English programmable output mode hints. + * Initializers for multi-language strings can be found in pcpslstr.h. + * + * @see ::POUT_MODES + * @see ::DEFAULT_ENG_POUT_HINTS + * + * @anchor ENG_POUT_HINTS @{ */ + #define ENG_POUT_HINT_IDLE "Constant output level" #define ENG_POUT_HINT_TIMER "Switch based on configured on/off times" #define ENG_POUT_HINT_SINGLE_SHOT "Generate a single pulse of determined length" @@ -4836,7 +6523,17 @@ enum POUT_MODES #define ENG_POUT_HINT_SYNTH "Frequency generated by programmable synthesizer" #define ENG_POUT_HINT_TIME_SLOTS "Output enabled during specified time slots per minute" #define ENG_POUT_HINT_GPIO "Duplicated signal of the specified GPIO input or output" +#define ENG_POUT_HINT_PTTI_PPS "Generate 20us Pulse at beginning of the second" +#define ENG_POUT_HINT_HAVEQUICK "Duplicated HaveQuick Signal" + +/** @} anchor ENG_POUT_HINTS */ + +/** + * @brief An initializer for a table of English POUT hint strings + * + * @see @ref ENG_POUT_HINTS + */ #define DEFAULT_ENG_POUT_HINTS \ { \ ENG_POUT_HINT_IDLE, \ @@ -4856,7 +6553,9 @@ enum POUT_MODES ENG_POUT_HINT_DCF77_M59, \ ENG_POUT_HINT_SYNTH, \ ENG_POUT_HINT_TIME_SLOTS, \ - ENG_POUT_HINT_GPIO \ + ENG_POUT_HINT_GPIO, \ + ENG_POUT_HINT_PTTI_PPS, \ + ENG_POUT_HINT_HAVEQUICK \ } @@ -4868,9 +6567,27 @@ enum POUT_MODES */ enum POUT_SETTINGS_FLAG_BITS { - POUT_BIT_INVERTED, ///< output level is inverted, use only if ::POUT_NOT_INVERTIBLE not set - POUT_BIT_IF_SYNC_ONLY, ///< disable output in holdover mode, use only if ::POUT_SUPP_IF_SYNC_ONLY is set - POUT_BIT_TIMEBASE_UTC, ///< output %UTC if mode is ::POUT_DCF77 or ::POUT_DCF77_M59, use only if ::POUT_SUPP_DCF77_UTC is set + /// Output level is to be inverted. Can only be used + /// if ::POUT_NOT_INVERTIBLE is ***not*** set, but is + /// supported by all ::POUT_MODES. + POUT_BIT_INVERTED, + + /// Enable output **only** while synchronized. This even overrides + /// the settings in ::ENABLE_FLAGS::pulses, so if this flag is set + /// the output is only enabled if the clock is synchronized, and is + /// disabled when synchronization is lost, i.e. the device enters + /// holdover mode. + /// This flag can only be used with outputs that have ::POUT_SUPP_IF_SYNC_ONLY + /// set, and is only supported for the ::POUT_MODES specified in + /// ::POUT_MODES_SUPP_IF_SYNC_ONLY. + POUT_BIT_IF_SYNC_ONLY, + + /// Output %UTC time instead of local time for DCF77 emulation. + /// This flag can only be used with outputs that have ::POUT_SUPP_DCF77_UTC + /// set, and is only supported for the ::POUT_MODES specified in + /// ::POUT_MODES_SUPP_TIMEBASE_UTC (e.g. ::POUT_DCF77 or ::POUT_DCF77_M59). + POUT_BIT_TIMEBASE_UTC, + N_POUT_SETTINGS_FLAG_BITS ///< Number of known flag bits }; @@ -4882,9 +6599,9 @@ enum POUT_SETTINGS_FLAG_BITS */ enum POUT_SETTINGS_FLAGS { - POUT_INVERTED = ( 1UL << POUT_BIT_INVERTED ), ///< see ::POUT_BIT_INVERTED, ::POUT_NOT_INVERTIBLE - POUT_IF_SYNC_ONLY = ( 1UL << POUT_BIT_IF_SYNC_ONLY ), ///< see ::POUT_BIT_IF_SYNC_ONLY, ::POUT_SUPP_IF_SYNC_ONLY - POUT_TIMEBASE_UTC = ( 1UL << POUT_BIT_TIMEBASE_UTC ) ///< see ::POUT_BIT_TIMEBASE_UTC, ::POUT_SUPP_DCF77_UTC + POUT_INVERTED = ( 1UL << POUT_BIT_INVERTED ), ///< See ::POUT_BIT_INVERTED, ::POUT_NOT_INVERTIBLE + POUT_IF_SYNC_ONLY = ( 1UL << POUT_BIT_IF_SYNC_ONLY ), ///< See ::POUT_BIT_IF_SYNC_ONLY, ::POUT_SUPP_IF_SYNC_ONLY + POUT_TIMEBASE_UTC = ( 1UL << POUT_BIT_TIMEBASE_UTC ) ///< See ::POUT_BIT_TIMEBASE_UTC, ::POUT_SUPP_DCF77_UTC }; @@ -4901,22 +6618,24 @@ enum POUT_SETTINGS_FLAGS */ typedef struct { - uint16_t idx; ///< 0..::RECEIVER_INFO::n_prg_out-1 + MBG_MSG_IDX idx; ///< 0..::RECEIVER_INFO::n_prg_out-1 POUT_SETTINGS pout_settings; } POUT_SETTINGS_IDX; #define _mbg_swab_pout_settings_idx_on_set( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_pout_settings_on_set( &(_p)->pout_settings ); \ -} +} while ( 0 ) #define _mbg_swab_pout_settings_idx_on_get( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_pout_settings_on_get( &(_p)->pout_settings ); \ -} +} while ( 0 ) /** @@ -4932,21 +6651,24 @@ typedef struct typedef struct { POUT_SETTINGS pout_settings; - uint32_t supp_modes; ///< bit mask of modes supp. by this output, see @ref POUT_MODE_MASKS - uint8_t timestr_ports; ///< bit mask of COM ports supported for mode ::POUT_TIMESTR, see ::MAX_POUT_TIMESTR_PORTS - uint8_t reserved_0; ///< reserved for future use, currently unused and always 0 - uint16_t reserved_1; ///< reserved for future use, currently unused and always 0 - uint32_t flags; ///< @see ::POUT_INFO_FLAG_MASKS + uint32_t supp_modes; ///< bit mask of modes supp. by this output, see @ref POUT_MODE_MASKS + uint8_t timestr_ports; ///< bit mask of COM ports supported for mode ::POUT_TIMESTR, see ::MAX_POUT_TIMESTR_PORTS + uint8_t pulse_shift_res; ///< pulse shift resolution, in [ns], only if ::POUT_SUPP_PULSE_SHIFT, see ::POUT_DATA::pulse_shift + uint16_t reserved_1; ///< reserved for future use, currently unused and always 0 + uint32_t flags; ///< @see ::POUT_INFO_FLAG_MASKS } POUT_INFO; #define _mbg_swab_pout_info_on_get( _p ) \ +do \ { \ _mbg_swab_pout_settings_on_get( &(_p)->pout_settings ); \ _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab8( &(_p)->timestr_ports ); \ + _mbg_swab8( &(_p)->pulse_shift_res ); \ _mbg_swab16( &(_p)->reserved_1 ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) #define MAX_POUT_TIMESTR_PORTS 8 ///< The max number of COM ports that can be handled by ::POUT_INFO::timestr_ports @@ -4964,6 +6686,7 @@ enum POUT_INFO_FLAG_BITS POUT_BIT_SUPP_DCF77_UTC, ///< ::POUT_SUPP_DCF77_UTC is supported for this output POUT_BIT_FIXED_PULSE_LEN, ///< pulse length is limited to the value ::POUT_SETTINGS::mode_param POUT_BIT_NOT_INVERTIBLE, ///< output level can't be inverted, thus ::POUT_INVERTED is not supported for this output + POUT_BIT_SUPP_PULSE_SHIFT, ///< output slopes can be shifted, see ::POUT_DATA::pulse_shift N_POUT_INFO_FLAG_BITS ///< number of known flag bits }; @@ -4975,10 +6698,11 @@ enum POUT_INFO_FLAG_BITS */ enum POUT_INFO_FLAG_MASKS { - POUT_SUPP_IF_SYNC_ONLY = ( 1UL << POUT_BIT_SUPP_IF_SYNC_ONLY ), ///< see ::POUT_BIT_SUPP_IF_SYNC_ONLY, ::POUT_IF_SYNC_ONLY - POUT_SUPP_DCF77_UTC = ( 1UL << POUT_BIT_SUPP_DCF77_UTC ), ///< see ::POUT_BIT_SUPP_DCF77_UTC, ::POUT_SUPP_DCF77_UTC - POUT_FIXED_PULSE_LEN = ( 1UL << POUT_BIT_FIXED_PULSE_LEN ), ///< see ::POUT_BIT_FIXED_PULSE_LEN - POUT_NOT_INVERTIBLE = ( 1UL << POUT_BIT_NOT_INVERTIBLE ) ///< see ::POUT_BIT_NOT_INVERTIBLE, ::POUT_INVERTED + POUT_SUPP_IF_SYNC_ONLY = ( 1UL << POUT_BIT_SUPP_IF_SYNC_ONLY ), ///< See ::POUT_BIT_SUPP_IF_SYNC_ONLY, ::POUT_IF_SYNC_ONLY + POUT_SUPP_DCF77_UTC = ( 1UL << POUT_BIT_SUPP_DCF77_UTC ), ///< See ::POUT_BIT_SUPP_DCF77_UTC, ::POUT_SUPP_DCF77_UTC + POUT_FIXED_PULSE_LEN = ( 1UL << POUT_BIT_FIXED_PULSE_LEN ), ///< See ::POUT_BIT_FIXED_PULSE_LEN + POUT_NOT_INVERTIBLE = ( 1UL << POUT_BIT_NOT_INVERTIBLE ), ///< See ::POUT_BIT_NOT_INVERTIBLE, ::POUT_INVERTED + POUT_SUPP_PULSE_SHIFT = ( 1UL << POUT_BIT_SUPP_PULSE_SHIFT ) ///< See ::POUT_BIT_SUPP_PULSE_SHIFT, ::POUT_DATA::pulse_shift }; @@ -4996,16 +6720,19 @@ enum POUT_INFO_FLAG_MASKS */ typedef struct { - uint16_t idx; ///< 0..::RECEIVER_INFO::n_prg_out-1 + MBG_MSG_IDX idx; ///< 0..::RECEIVER_INFO::n_prg_out-1 POUT_INFO pout_info; } POUT_INFO_IDX; #define _mbg_swab_pout_info_idx_on_get( _p ) \ +do \ { \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab_pout_info_on_get( &(_p)->pout_info ); \ -} +} while ( 0 ) + +/** @} defgroup group_pout_api */ @@ -5044,7 +6771,7 @@ typedef struct /** * @brief Enumeration of all known types of reference time source * - * All known types of input signals which may possibly be supported + * All known types of input signal which may possibly be supported * by devices which support several different input signals, i.e. * have the ::GPS_HAS_MULTI_REF or ::GPS_HAS_XMULTI_REF bit set * in ::RECEIVER_INFO::features. Not all devices support each known @@ -5057,9 +6784,10 @@ typedef struct */ enum MULTI_REF_TYPES { - /// This ref type must not be used as index, but marks particular - /// ::XMULTI_REF_SETTINGS structures as "unused". It is only - /// supported if bit ::XMRIF_BIT_MRF_NONE_SUPP is set + /// @brief This ref type must not be used as index. + /// + /// It marks particular ::XMULTI_REF_SETTINGS structures as "unused". + /// This is only supported if bit ::XMRIF_BIT_MRF_NONE_SUPP is set. MULTI_REF_NONE = -1, MULTI_REF_GPS = 0, ///< standard GPS @@ -5079,6 +6807,9 @@ enum MULTI_REF_TYPES MULTI_REF_GRC, ///< Glonass / GPS receiver MULTI_REF_HAVEQUICK, ///< HaveQuick input MULTI_REF_EXT_OSC, ///< external oscillator disciplined and looped back via 1 PPS I/O + MULTI_REF_SYNCE, ///< Synchronous Ethernet, needs (external) ethernet interface + MULTI_REF_VIDEO_IN, ///< Video In (Blackburst, VITC,...) + MULTI_REF_LTC, ///< Linear Time Code (Audio) N_MULTI_REF ///< the number of defined sources, must not exceed ::MAX_N_MULTI_REF_TYPES }; @@ -5112,9 +6843,12 @@ enum MULTI_REF_TYPES "(reserved)", \ "DCF77 PZF Receiver", \ "Long Wave Receiver", \ - "GLONASS/GPS Receiver", \ + "GNSS Receiver", \ "HaveQuick Input", \ - "ext. Osc." \ + "ext. Osc.", \ + "Synchronous Ethernet", \ + "Video Input", \ + "Linear Time Code" \ } /** @@ -5132,17 +6866,20 @@ enum MULTI_REF_TYPES "10MHZ+PPS", \ "TCR", \ "NTP", \ - "PTP hq", \ - "PTP E1", \ - "Fixed in", \ - "STR in", \ - "GPIO in", \ + "PTP", \ + "PTP_E1", \ + "FIXED_FREQ", \ + "STRING+PPS", \ + "GPIO", \ "(reserved)", \ "PZF", \ "LWR", \ - "GGR", \ + "GNSS", \ "HQI", \ - "EXT" \ + "EXT", \ + "SYNCE", \ + "VIDEO_IN", \ + "LTC" \ } @@ -5156,25 +6893,29 @@ enum MULTI_REF_TYPES * * @anchor MULTI_REF_TYPE_MASKS @{ */ -#define HAS_MULTI_REF_GPS ( 1UL << MULTI_REF_GPS ) ///< see ::MULTI_REF_GPS -#define HAS_MULTI_REF_10MHZ ( 1UL << MULTI_REF_10MHZ ) ///< see ::MULTI_REF_10MHZ -#define HAS_MULTI_REF_PPS ( 1UL << MULTI_REF_PPS ) ///< see ::MULTI_REF_PPS -#define HAS_MULTI_REF_10MHZ_PPS ( 1UL << MULTI_REF_10MHZ_PPS ) ///< see ::MULTI_REF_10MHZ_PPS -#define HAS_MULTI_REF_IRIG ( 1UL << MULTI_REF_IRIG ) ///< see ::MULTI_REF_IRIG -#define HAS_MULTI_REF_NTP ( 1UL << MULTI_REF_NTP ) ///< see ::MULTI_REF_NTP -#define HAS_MULTI_REF_PTP ( 1UL << MULTI_REF_PTP ) ///< see ::MULTI_REF_PTP -#define HAS_MULTI_REF_PTP_E1 ( 1UL << MULTI_REF_PTP_E1 ) ///< see ::MULTI_REF_PTP_E1 - -#define HAS_MULTI_REF_FREQ ( 1UL << MULTI_REF_FREQ ) ///< see ::MULTI_REF_FREQ -#define HAS_MULTI_REF_PPS_STRING ( 1UL << MULTI_REF_PPS_STRING ) ///< see ::MULTI_REF_PPS_STRING -#define HAS_MULTI_REF_GPIO ( 1UL << MULTI_REF_GPIO ) ///< see ::MULTI_REF_GPIO -#define HAS_MULTI_REF_INTERNAL ( 1UL << MULTI_REF_INTERNAL ) ///< see ::MULTI_REF_INTERNAL -#define HAS_MULTI_REF_PZF ( 1UL << MULTI_REF_PZF ) ///< see ::MULTI_REF_PZF -#define HAS_MULTI_REF_LWR ( 1UL << MULTI_REF_LWR ) ///< see ::MULTI_REF_LWR -#define HAS_MULTI_REF_GRC ( 1UL << MULTI_REF_GRC ) ///< see ::MULTI_REF_GRC -#define HAS_MULTI_REF_HAVEQUICK ( 1UL << MULTI_REF_HAVEQUICK ) ///< see ::MULTI_REF_HAVEQUICK - -#define HAS_MULTI_REF_EXT_OSC ( 1UL << MULTI_REF_EXT_OSC ) ///< see ::MULTI_REF_EXT_OSC +#define HAS_MULTI_REF_GPS ( 1UL << MULTI_REF_GPS ) ///< See ::MULTI_REF_GPS +#define HAS_MULTI_REF_10MHZ ( 1UL << MULTI_REF_10MHZ ) ///< See ::MULTI_REF_10MHZ +#define HAS_MULTI_REF_PPS ( 1UL << MULTI_REF_PPS ) ///< See ::MULTI_REF_PPS +#define HAS_MULTI_REF_10MHZ_PPS ( 1UL << MULTI_REF_10MHZ_PPS ) ///< See ::MULTI_REF_10MHZ_PPS +#define HAS_MULTI_REF_IRIG ( 1UL << MULTI_REF_IRIG ) ///< See ::MULTI_REF_IRIG +#define HAS_MULTI_REF_NTP ( 1UL << MULTI_REF_NTP ) ///< See ::MULTI_REF_NTP +#define HAS_MULTI_REF_PTP ( 1UL << MULTI_REF_PTP ) ///< See ::MULTI_REF_PTP +#define HAS_MULTI_REF_PTP_E1 ( 1UL << MULTI_REF_PTP_E1 ) ///< See ::MULTI_REF_PTP_E1 + +#define HAS_MULTI_REF_FREQ ( 1UL << MULTI_REF_FREQ ) ///< See ::MULTI_REF_FREQ +#define HAS_MULTI_REF_PPS_STRING ( 1UL << MULTI_REF_PPS_STRING ) ///< See ::MULTI_REF_PPS_STRING +#define HAS_MULTI_REF_GPIO ( 1UL << MULTI_REF_GPIO ) ///< See ::MULTI_REF_GPIO +#define HAS_MULTI_REF_INTERNAL ( 1UL << MULTI_REF_INTERNAL ) ///< See ::MULTI_REF_INTERNAL +#define HAS_MULTI_REF_PZF ( 1UL << MULTI_REF_PZF ) ///< See ::MULTI_REF_PZF +#define HAS_MULTI_REF_LWR ( 1UL << MULTI_REF_LWR ) ///< See ::MULTI_REF_LWR +#define HAS_MULTI_REF_GRC ( 1UL << MULTI_REF_GRC ) ///< See ::MULTI_REF_GRC +#define HAS_MULTI_REF_HAVEQUICK ( 1UL << MULTI_REF_HAVEQUICK ) ///< See ::MULTI_REF_HAVEQUICK + +#define HAS_MULTI_REF_EXT_OSC ( 1UL << MULTI_REF_EXT_OSC ) ///< See ::MULTI_REF_EXT_OSC +#define HAS_MULTI_REF_SYNCE ( 1UL << MULTI_REF_SYNCE ) ///< See ::MULTI_REF_SYNCE +#define HAS_MULTI_REF_VIDEO_IN ( 1UL << MULTI_REF_VIDEO_IN ) ///< See ::MULTI_REF_VIDEO_IN +#define HAS_MULTI_REF_LTC ( 1UL << MULTI_REF_LTC ) ///< See ::MULTI_REF_LTC + /** @} anchor MULTI_REF_TYPE_MASKS */ @@ -5269,15 +7010,15 @@ enum MULTI_REF_STATUS_BITS */ enum MULTI_REF_STATUS_BIT_MASKS { - MSK_WRN_COLD_BOOT = ( 1UL << WRN_COLD_BOOT ), ///< see ::WRN_COLD_BOOT - MSK_WRN_WARM_BOOT = ( 1UL << WRN_WARM_BOOT ), ///< see ::WRN_WARM_BOOT - MSK_WRN_ANT_DISCONN = ( 1UL << WRN_ANT_DISCONN ), ///< see ::WRN_ANT_DISCONN - MSK_WRN_10MHZ_UNLOCK = ( 1UL << WRN_10MHZ_UNLOCK ), ///< see ::WRN_10MHZ_UNLOCK - MSK_WRN_1PPS_UNLOCK = ( 1UL << WRN_1PPS_UNLOCK ), ///< see ::WRN_1PPS_UNLOCK - MSK_WRN_GPS_UNLOCK = ( 1UL << WRN_GPS_UNLOCK ), ///< see ::WRN_GPS_UNLOCK - MSK_WRN_10MHZ_MISSING = ( 1UL << WRN_10MHZ_MISSING ), ///< see ::WRN_10MHZ_MISSING - MSK_WRN_1PPS_MISSING = ( 1UL << WRN_1PPS_MISSING ), ///< see ::WRN_1PPS_MISSING - MSK_WRN_MODULE_MODE = ( 1UL << WRN_MODULE_MODE ) ///< see ::WRN_MODULE_MODE + MSK_WRN_COLD_BOOT = ( 1UL << WRN_COLD_BOOT ), ///< See ::WRN_COLD_BOOT + MSK_WRN_WARM_BOOT = ( 1UL << WRN_WARM_BOOT ), ///< See ::WRN_WARM_BOOT + MSK_WRN_ANT_DISCONN = ( 1UL << WRN_ANT_DISCONN ), ///< See ::WRN_ANT_DISCONN + MSK_WRN_10MHZ_UNLOCK = ( 1UL << WRN_10MHZ_UNLOCK ), ///< See ::WRN_10MHZ_UNLOCK + MSK_WRN_1PPS_UNLOCK = ( 1UL << WRN_1PPS_UNLOCK ), ///< See ::WRN_1PPS_UNLOCK + MSK_WRN_GPS_UNLOCK = ( 1UL << WRN_GPS_UNLOCK ), ///< See ::WRN_GPS_UNLOCK + MSK_WRN_10MHZ_MISSING = ( 1UL << WRN_10MHZ_MISSING ), ///< See ::WRN_10MHZ_MISSING + MSK_WRN_1PPS_MISSING = ( 1UL << WRN_1PPS_MISSING ), ///< See ::WRN_1PPS_MISSING + MSK_WRN_MODULE_MODE = ( 1UL << WRN_MODULE_MODE ) ///< See ::WRN_MODULE_MODE }; /** @} defgroup group_multi_ref_old */ @@ -5289,22 +7030,21 @@ enum MULTI_REF_STATUS_BIT_MASKS * * If the ::GPS_HAS_XMULTI_REF feature is set in ::RECEIVER_INFO::features then * the XMULTI_REF (extended multi ref, XMR) feature and API are supported and - * must be used in favor of the older multi ref API (see @ref group_multi_ref_old). + * have to be used in favor of the older multi ref API (see @ref group_multi_ref_old). * * Devices supporting the XMULTI_REF feature provide a number of * priority levels addressed by the priority index, starting at 0 * for highest priority. A single reference time source from the set * of supported sources can be assigned to each priority level. * - * These structures are used to configure the individual - * time source for each priority level, and retrieve the status - * of the time source at each priority level. + * These structures are used to configure the individual time source for each + * priority level, and retrieve the status of the time source at each priority level. * * If ::GPS_HAS_XMRS_MULT_INSTC is also set in ::RECEIVER_INFO::features then * ::XMULTI_REF_INSTANCES can be used to find out which types of input source * are supported (::XMULTI_REF_INSTANCES::n_inst array entries != 0), and - * how many priority levels are supported to get an input source assigned - * (::XMULTI_REF_INSTANCES::n_xmr_settings). + * how many priority levels are supported to which an input source can be + * assigned (::XMULTI_REF_INSTANCES::n_xmr_settings). * * If ::XMRIF_MSK_HOLDOVER_STATUS_SUPP is set in ::XMULTI_REF_INSTANCES::flags * then ::XMR_HOLDOVER_STATUS can be used to monitor the switching between @@ -5340,11 +7080,18 @@ enum MULTI_REF_STATUS_BIT_MASKS */ typedef struct { - uint8_t type; ///< see ::MULTI_REF_TYPES, and note for ::XMRIF_BIT_MRF_NONE_SUPP + uint8_t type; ///< See ::MULTI_REF_TYPES, and note for ::XMRIF_BIT_MRF_NONE_SUPP uint8_t instance; ///< instance number, if multiple instances are supported, else 0 } XMULTI_REF_ID; +#define _mbg_swab_xmulti_ref_id( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->type ); \ + _mbg_swab8( &(_p)->instance ); \ +} while ( 0 ) + /** @@ -5353,13 +7100,23 @@ typedef struct typedef struct { XMULTI_REF_ID id; ///< reference time source identifier - uint16_t flags; ///< reserved, currently always 0 + uint16_t flags; ///< See ::XMR_SETTINGS_FLAG_MSKS and ::XMR_EXT_SRC_INFO::supp_flags NANO_TIME bias; ///< time bias, e.g. path delay @todo specify sign vs. earlier/later NANO_TIME precision; ///< precision of the time source uint32_t reserved; ///< reserved, currently always 0 } XMULTI_REF_SETTINGS; +#define _mbg_swab_xmulti_ref_settings( _p ) \ +do \ +{ \ + _mbg_swab_xmulti_ref_id( &(_p)->id ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab_nano_time( &(_p)->bias ); \ + _mbg_swab_nano_time( &(_p)->precision ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + /** @@ -5371,11 +7128,50 @@ typedef struct */ typedef struct { - uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1 - XMULTI_REF_SETTINGS settings; ///< the settings configured for this level + MBG_MSG_IDX idx; ///< The priority level index, 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, 0 == highest. + XMULTI_REF_SETTINGS settings; ///< The settings configured for this level. } XMULTI_REF_SETTINGS_IDX; +#define _mbg_swab_xmulti_ref_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmulti_ref_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Bit masks used to define ::XMR_SETTINGS_FLAG_MSKS + */ +enum XMR_SETTINGS_FLAG_BITS +{ + XMRSF_BIT_AUTO_BIAS_MASTER, ///< src is allowed to operate as zero asymmetry master + XMRSF_BIT_AUTO_BIAS_SLAVE, ///< accept static bias correction from zero asymmetry master + XMRSF_BIT_ASYMMETRY_STEP_DETECTION, ///< static bias auto correction in case of step + XMRSF_BIT_IS_TRUSTED_SRC, ///< src can be used as a trusted src for spoofing detection + XMRSF_BIT_USE_TRUSTED_SRC, ///< use a trusted source for consistency check and spoofing detection + XMRSF_BIT_IS_TIME_OF_DAY_SRC, ///< src can be used for time of day synchronization + XMRSF_BIT_IS_PHASE_SRC, ///< src can be used for phase synchronization + N_XMRSF_BITS ///< number of known flag bits +}; + + +/** + * @brief Bit masks used with ::XMULTI_REF_SETTINGS::flags and ::XMR_EXT_SRC_INFO::supp_flags + */ +enum XMR_SETTINGS_FLAG_MSKS +{ + XMRSF_MSK_AUTO_BIAS_MASTER = ( 1UL << XMRSF_BIT_AUTO_BIAS_MASTER ), ///< See ::XMRSF_BIT_AUTO_BIAS_MASTER + XMRSF_MSK_AUTO_BIAS_SLAVE = ( 1UL << XMRSF_BIT_AUTO_BIAS_SLAVE ), ///< See ::XMRSF_BIT_AUTO_BIAS_SLAVE + XMRSF_MSK_ASYMMETRY_STEP_DETECTION = ( 1UL << XMRSF_BIT_ASYMMETRY_STEP_DETECTION ), ///< See ::XMRSF_BIT_ASYMMETRY_STEP_DETECTION + XMRSF_MSK_IS_TRUSTED_SRC = ( 1UL << XMRSF_BIT_IS_TRUSTED_SRC ), ///< See ::XMRSF_BIT_IS_TRUSTED_SRC + XMRSF_MSK_USE_TRUSTED_SRC = ( 1UL << XMRSF_BIT_USE_TRUSTED_SRC ), ///< See ::XMRSF_BIT_USE_TRUSTED_SRC + XMRSF_MSK_IS_TIME_OF_DAY_SRC = ( 1UL << XMRSF_BIT_IS_TIME_OF_DAY_SRC ), ///< See ::XMRSF_BIT_IS_TIME_OF_DAY_SRC + XMRSF_MSK_IS_PHASE_SRC = ( 1UL << XMRSF_BIT_IS_PHASE_SRC ) ///< See ::XMRSF_BIT_IS_PHASE_SRC +}; + /** @@ -5387,7 +7183,7 @@ typedef struct /** * @deprecated Deprecated by ::XMULTI_REF_INSTANCES::n_inst. - * If ::GPS_HAS_XMRS_MULT_INSTC is *not* set then this field provides + * If ::GPS_HAS_XMRS_MULT_INSTC is ***not*** set then this field provides * a bit mask of supported sources (see @ref MULTI_REF_TYPE_MASKS), * and only a single instance of each source signal type is supported. */ @@ -5395,16 +7191,26 @@ typedef struct /** * @deprecated Deprecated by ::XMULTI_REF_INSTANCES::n_xmr_settings. - * If ::GPS_HAS_XMRS_MULT_INSTC is *not* set then this field + * If ::GPS_HAS_XMRS_MULT_INSTC is ***not*** set then this field * reports the number of priority levels supported by the device. */ uint8_t n_supp_ref; - uint8_t reserved; ///< reserved, don't use, currently always 0 - uint16_t flags; ///< reserved, don't use, currently always 0 + uint8_t n_prio; ///< reserved, don't use, currently always 0 //##++++ TODO: check which devices support/use this field + uint16_t flags; ///< reserved, don't use, currently always 0 } XMULTI_REF_INFO; +#define _mbg_swab_xmulti_ref_info( _p ) \ +do \ +{ \ + _mbg_swab_xmulti_ref_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_ref ); \ + _mbg_swab8( &(_p)->n_supp_ref ); \ + _mbg_swab8( &(_p)->n_prio ); \ + _mbg_swab16( &(_p)->flags ); \ +} while ( 0 ) + /** @@ -5412,11 +7218,18 @@ typedef struct */ typedef struct { - uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1 - XMULTI_REF_INFO info; ///< ref source configuration and capabilities + MBG_MSG_IDX idx; ///< The priority level index, 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, 0 == highest. + XMULTI_REF_INFO info; ///< Ref. source configuration and capabilities. } XMULTI_REF_INFO_IDX; +#define _mbg_swab_xmulti_ref_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmulti_ref_info( &(_p)->info ); \ +} while ( 0 ) + /** @@ -5427,12 +7240,23 @@ typedef struct XMULTI_REF_ID id; ///< time source identifier uint16_t status; ///< status bits, see @ref XMR_REF_STATUS_BIT_MASKS NANO_TIME offset; ///< time offset from main time base @todo specify sign vs. earlier/later - uint16_t flags; ///< flags, currently unused + uint16_t flags; ///< flags, see ::XMR_QL // TODO ### uint8_t ssm; ///< synchronization status message, if supported by signal source uint8_t soc; ///< signal outage counter, incremented on loss of signal } XMULTI_REF_STATUS; +#define _mbg_swab_xmulti_ref_status( _p ) \ +do \ +{ \ + _mbg_swab_xmulti_ref_id( &(_p)->id ); \ + _mbg_swab16( &(_p)->status ); \ + _mbg_swab_nano_time( &(_p)->offset ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab8( &(_p)->ssm ); \ + _mbg_swab8( &(_p)->soc ); \ +} while ( 0 ) + /** @@ -5440,11 +7264,58 @@ typedef struct */ typedef struct { - uint16_t idx; ///< the priority level index (highest == 0), 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1 - XMULTI_REF_STATUS status; ///< status information + MBG_MSG_IDX idx; ///< The priority level index, 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, 0 == highest. + XMULTI_REF_STATUS status; ///< Status information. } XMULTI_REF_STATUS_IDX; +#define _mbg_swab_xmulti_ref_status_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmulti_ref_status( &(_p)->status ); \ +} while ( 0 ) + + + +/** + * @brief ::TODO + * + * Used with the ::... field of ::XMULTI_REF_STATUS::flags + * + * @see ::XMULTI_REF_STATUS::flags + * @see ::XMR_QL_TDEV_MASK + * @see ::_GET_XMR_QL_TDEV + * @see ::_PUT_XMR_QL_TDEV + * @see ::XMR_QL_MTIE_MASK + * @see ::_GET_XMR_QL_MTIE + * @see ::_PUT_XMR_QL_MTIE + */ +enum XMR_QL +{ + XMR_QL_UNKNOWN, + XMR_QL_GREEN, + XMR_QL_YELLOW, + XMR_QL_RED, + N_XMR_QL +}; + +#define XMR_QL_TDEV_MASK ( 0x03 << 0 ) +#define XMR_QL_MTIE_MASK ( 0x03 << 2 ) + +#define _GET_XMR_QL_TDEV( _x ) ( ( ( _x ) & XMR_QL_TDEV_MASK ) >> 0 ) +#define _PUT_XMR_QL_TDEV( _x, _ql ) \ +do { \ + ( _x ) = ( ( _x ) & ~XMR_QL_TDEV_MASK ) | ( ( ( _ql ) << 0 ) & XMR_QL_TDEV_MASK ); \ +} while ( 0 ) + + +#define _GET_XMR_QL_MTIE( _x ) ( ( ( _x ) & XMR_QL_MTIE_MASK ) >> 2 ) +#define _PUT_XMR_QL_MTIE( _x, _ql ) \ +do { \ + ( _x ) = ( ( _x ) & ~XMR_QL_MTIE_MASK ) | ( ( ( _ql ) << 2 ) & XMR_QL_MTIE_MASK ); \ +} while ( 0 ) + /** @@ -5452,21 +7323,24 @@ typedef struct */ enum XMR_REF_STATUS_BITS { - XMRS_BIT_NOT_SUPP, ///< ref type cfg'd for this level is not supported - XMRS_BIT_NO_CONN, ///< input signal is disconnected - XMRS_BIT_NO_SIGNAL, ///< no input signal - XMRS_BIT_IS_MASTER, ///< reference is master source - XMRS_BIT_IS_LOCKED, ///< locked to input signal - XMRS_BIT_IS_ACCURATE, ///< oscillator control has reached full accuracy - XMRS_BIT_NOT_SETTLED, ///< reference time signal not settled - XMRS_BIT_NOT_PHASE_LOCKED, ///< oscillator not phase locked to PPS - XMRS_BIT_NUM_SRC_EXC, ///< number of available sources exceeds what can be handled - XMRS_BIT_IS_EXTERNAL, ///< this ref source is on extension card - XMRS_BIT_LOW_JITTER, ///< this ref source has low jitter - N_XMRS_BITS ///< number of know status bits + XMRS_BIT_NOT_SUPP, ///< ref type cfg'd for this level is not supported + XMRS_BIT_NO_CONN, ///< input signal is disconnected + XMRS_BIT_NO_SIGNAL, ///< no input signal + XMRS_BIT_IS_MASTER, ///< reference is master source + XMRS_BIT_IS_LOCKED, ///< locked to input signal + XMRS_BIT_IS_ACCURATE, ///< oscillator control has reached full accuracy + XMRS_BIT_NOT_SETTLED, ///< reference time signal not settled + XMRS_BIT_NOT_PHASE_LOCKED, ///< oscillator not phase locked to PPS + XMRS_BIT_NUM_SRC_EXC, ///< number of available sources exceeds what can be handled + XMRS_BIT_IS_EXTERNAL, ///< this ref source is on extension card + XMRS_BIT_LOW_JITTER, ///< this ref source has low jitter + XMRS_BIT_ITU_LIMIT_VIOLATED, ///< ITU limits violated (valid if device has ::XMR_METRICS) + XMRS_BIT_TRS_LIMIT_VIOLATED, ///< Trusted source offset limit violated (valid if device has ::XMRSF_MSK_USE_TRUSTED_SRC) + N_XMRS_BITS ///< number of know status bits }; + /** * @brief Bit masks associated with ::XMR_REF_STATUS_BITS * @@ -5476,21 +7350,24 @@ enum XMR_REF_STATUS_BITS * * @anchor XMR_REF_STATUS_BIT_MASKS @{ */ -#define XMRS_MSK_NOT_SUPP ( 1UL << XMRS_BIT_NOT_SUPP ) ///< see ::XMRS_BIT_NOT_SUPP -#define XMRS_MSK_NO_CONN ( 1UL << XMRS_BIT_NO_CONN ) ///< see ::XMRS_BIT_NO_CONN -#define XMRS_MSK_NO_SIGNAL ( 1UL << XMRS_BIT_NO_SIGNAL ) ///< see ::XMRS_BIT_NO_SIGNAL -#define XMRS_MSK_IS_MASTER ( 1UL << XMRS_BIT_IS_MASTER ) ///< see ::XMRS_BIT_IS_MASTER -#define XMRS_MSK_IS_LOCKED ( 1UL << XMRS_BIT_IS_LOCKED ) ///< see ::XMRS_BIT_IS_LOCKED -#define XMRS_MSK_IS_ACCURATE ( 1UL << XMRS_BIT_IS_ACCURATE ) ///< see ::XMRS_BIT_IS_ACCURATE -#define XMRS_MSK_NOT_SETTLED ( 1UL << XMRS_BIT_NOT_SETTLED ) ///< see ::XMRS_BIT_NOT_SETTLED -#define XMRS_MSK_NOT_PHASE_LOCKED ( 1UL << XMRS_BIT_NOT_PHASE_LOCKED ) ///< see ::XMRS_BIT_NOT_PHASE_LOCKED -#define XMRS_MSK_NUM_SRC_EXC ( 1UL << XMRS_BIT_NUM_SRC_EXC ) ///< see ::XMRS_BIT_NUM_SRC_EXC -#define XMRS_MSK_IS_EXTERNAL ( 1UL << XMRS_BIT_IS_EXTERNAL ) ///< see ::XMRS_BIT_IS_EXTERNAL -#define XMRS_MSK_LOW_JITTER ( 1UL << XMRS_BIT_LOW_JITTER ) ///< see ::XMRS_BIT_LOW_JITTER +#define XMRS_MSK_NOT_SUPP ( 1UL << XMRS_BIT_NOT_SUPP ) ///< See ::XMRS_BIT_NOT_SUPP +#define XMRS_MSK_NO_CONN ( 1UL << XMRS_BIT_NO_CONN ) ///< See ::XMRS_BIT_NO_CONN +#define XMRS_MSK_NO_SIGNAL ( 1UL << XMRS_BIT_NO_SIGNAL ) ///< See ::XMRS_BIT_NO_SIGNAL +#define XMRS_MSK_IS_MASTER ( 1UL << XMRS_BIT_IS_MASTER ) ///< See ::XMRS_BIT_IS_MASTER +#define XMRS_MSK_IS_LOCKED ( 1UL << XMRS_BIT_IS_LOCKED ) ///< See ::XMRS_BIT_IS_LOCKED +#define XMRS_MSK_IS_ACCURATE ( 1UL << XMRS_BIT_IS_ACCURATE ) ///< See ::XMRS_BIT_IS_ACCURATE +#define XMRS_MSK_NOT_SETTLED ( 1UL << XMRS_BIT_NOT_SETTLED ) ///< See ::XMRS_BIT_NOT_SETTLED +#define XMRS_MSK_NOT_PHASE_LOCKED ( 1UL << XMRS_BIT_NOT_PHASE_LOCKED ) ///< See ::XMRS_BIT_NOT_PHASE_LOCKED +#define XMRS_MSK_NUM_SRC_EXC ( 1UL << XMRS_BIT_NUM_SRC_EXC ) ///< See ::XMRS_BIT_NUM_SRC_EXC +#define XMRS_MSK_IS_EXTERNAL ( 1UL << XMRS_BIT_IS_EXTERNAL ) ///< See ::XMRS_BIT_IS_EXTERNAL +#define XMRS_MSK_LOW_JITTER ( 1UL << XMRS_BIT_LOW_JITTER ) ///< See ::XMRS_BIT_LOW_JITTER +#define XMRS_MSK_ITU_LIMIT_VIOLATED ( 1UL << XMRS_BIT_ITU_LIMIT_VIOLATED ) ///< See ::XMRS_BIT_ITU_LIMIT_VIOLATED +#define XMRS_MSK_TRS_LIMIT_VIOLATED ( 1UL << XMRS_BIT_TRS_LIMIT_VIOLATED ) ///< See ::XMRS_BIT_TRS_LIMIT_VIOLATED /** @} anchor XMR_REF_STATUS_BIT_MASKS */ + /** * @brief XMRS status bit name strings * @@ -5508,10 +7385,13 @@ enum XMR_REF_STATUS_BITS "Phase not locked", \ "Number sources exceeds limit", \ "Is external", \ - "Low jitter" \ + "Low jitter", \ + "ITU Limit violated", \ + "TRS Limit violated" \ } + /* * An initializer for a ::XMULTI_REF_STATUS variable * with status invalid / not used @@ -5525,6 +7405,7 @@ enum XMR_REF_STATUS_BITS } + /** * @brief General info on supported XMR sources and instances * @@ -5552,14 +7433,44 @@ enum XMR_REF_STATUS_BITS */ typedef struct { - uint32_t flags; ///< see ::XMR_INST_FLAG_BIT_MASKS - uint16_t n_xmr_settings; ///< number of entries in the input source priority table + uint32_t flags; ///< See ::XMR_INST_FLAG_BIT_MASKS + uint16_t n_xmr_settings; ///< number of ::XMULTI_REF_INFO_IDX or ::XMULTI_REF_STATUS_IDX which can be retrieved uint8_t slot_id; ///< ID of the slot in which this device is installed, 0 or up to 15, if multiple slots not supported uint8_t reserved; ///< reserved, don't use, currently always 0 uint8_t n_inst[MAX_N_MULTI_REF_TYPES]; ///< the number of supported instances of each input signal type } XMULTI_REF_INSTANCES; +#define _mbg_swab_xmulti_ref_instances( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab16( &(_p)->n_xmr_settings ); \ +} while ( 0 ) + + + +/** + * @brief Extended information about the reference source of an instance type. + */ +typedef struct +{ + uint8_t integrated [MAX_N_MULTI_REF_TYPES]; ///< See ::SYS_REF_SRC_INTEGRATED + uint8_t peripheral [MAX_N_MULTI_REF_TYPES]; ///< See ::SYS_REF_SRC_PERIPHERAL + uint8_t expansion [MAX_N_MULTI_REF_TYPES]; ///< See ::SYS_REF_SRC_EXPANSION + uint8_t autarkic [MAX_N_MULTI_REF_TYPES]; ///< See ::SYS_REF_SRC_AUTARKIC + uint8_t reserved_1 [MAX_N_MULTI_REF_TYPES]; + uint8_t reserved_2 [MAX_N_MULTI_REF_TYPES]; + uint8_t reserved_3 [MAX_N_MULTI_REF_TYPES]; + uint8_t reserved_4 [MAX_N_MULTI_REF_TYPES]; + +} XMULTI_EXT_REF_INSTANCES; + +#define _mbg_swab_xmulti_ext_ref_instances( _p ) \ +do \ +{ \ +} while ( 0 ) + /** @@ -5569,16 +7480,25 @@ typedef struct */ enum XMR_INST_FLAGS { + /// @brief Indicate that the ::MULTI_REF_NONE pseude-type is supported is supported. + /// /// This flag indicates that configuration programs may set /// ::XMULTI_REF_ID::type to ::MULTI_REF_NONE in ::XMULTI_REF_SETTINGS::id - /// for unused priority levels, and that this will be reflected in + /// for unused priority levels, and that this will be reflected in /// ::XMULTI_REF_STATUS::id accordingly. With some older firmware versions /// this was not supported. XMRIF_BIT_MRF_NONE_SUPP, - XMRIF_BIT_HOLDOVER_STATUS_SUPP, ///< ::XMR_HOLDOVER_STATUS and associated types supported + XMRIF_BIT_HOLDOVER_STATUS_SUPP, ///< ::XMR_HOLDOVER_STATUS and associated types supported. + + XMRIF_BIT_EXT_SRC_INFO_SUPP, ///< ::XMR_EXT_SRC_INFO structure supported. + XMRIF_BIT_GNSS_BIAS_SUPP, ///< ::MULTI_REF_GPS or MULTI_REF_GRC can use XMULTI_REF_SETTINGS::bias. + + XMRIF_BIT_EXT_REF_INSTANCES_SUPP, ///< Supports ::XMULTI_EXT_REF_INSTANCES structure. + XMRIF_BIT_NOT_CONFIGURABLE, ///< ::XMULTI_REF_SETTINGS cannot be configured. + XMRIF_BIT_NO_STATUS, ///< No status, no stats at all. NOTHING!!! - N_XMRIF_BITS ///< number of known flag bits + N_XMRIF_BITS ///< Number of known flag bits. }; @@ -5591,18 +7511,24 @@ enum XMR_INST_FLAGS */ enum XMR_INST_FLAG_BIT_MASKS { - XMRIF_MSK_MRF_NONE_SUPP = ( 1UL << XMRIF_BIT_MRF_NONE_SUPP ), ///< see ::XMRIF_BIT_MRF_NONE_SUPP - XMRIF_MSK_HOLDOVER_STATUS_SUPP = ( 1UL << XMRIF_BIT_HOLDOVER_STATUS_SUPP ) ///< see ::XMRIF_BIT_HOLDOVER_STATUS_SUPP + XMRIF_MSK_MRF_NONE_SUPP = ( 1UL << XMRIF_BIT_MRF_NONE_SUPP ), ///< See ::XMRIF_BIT_MRF_NONE_SUPP + XMRIF_MSK_HOLDOVER_STATUS_SUPP = ( 1UL << XMRIF_BIT_HOLDOVER_STATUS_SUPP ), ///< See ::XMRIF_BIT_HOLDOVER_STATUS_SUPP + XMRIF_MSK_EXT_SRC_INFO_SUPP = ( 1UL << XMRIF_BIT_EXT_SRC_INFO_SUPP ), ///< See ::XMRIF_BIT_EXT_SRC_INFO_SUPP + XMRIF_MSK_GNSS_BIAS_SUPP = ( 1UL << XMRIF_BIT_GNSS_BIAS_SUPP ), ///< See ::XMRIF_BIT_GNSS_BIAS_SUPP + XMRIF_MSK_EXT_REF_INSTANCES_SUPP = ( 1UL << XMRIF_BIT_EXT_REF_INSTANCES_SUPP ), ///< See ::XMRIF_BIT_EXT_REF_INSTANCES_SUPP + XMRIF_MSK_NOT_CONFIGURABLE = ( 1UL << XMRIF_BIT_NOT_CONFIGURABLE ), ///< See ::XMRIF_BIT_NOT_CONFIGURABLE + XMRIF_MSK_NO_STATUS = ( 1UL << XMRIF_BIT_NO_STATUS ) ///< See ::XMRIF_BIT_NO_STATUS }; + /** * @brief XMR holdover interval, or elapsed holdover time, in [s] */ typedef uint32_t XMR_HOLDOVER_INTV; #define _mbg_swab_xmr_holdover_intv( _p ) \ - _mbg_swab32( _p ); + _mbg_swab32( _p ) @@ -5612,6 +7538,7 @@ typedef uint32_t XMR_HOLDOVER_INTV; #define XMR_PRIO_LVL_UNSPEC -1 + /** * @brief XMR holdover status * @@ -5639,19 +7566,34 @@ typedef uint32_t XMR_HOLDOVER_INTV; * starts to count down. If the watchdog expires before a remote switch command * has been received the device switches to ::XMR_HLDOVR_AUTONOMOUS. */ -typedef struct +typedef struct xmr_holdover_status_s { uint8_t mode; ///< XMR/holdover mode, see ::XMR_HOLDOVER_STATUS_MODES int8_t curr_prio; ///< current priority level, 0..::XMULTI_REF_INSTANCES::n_xmr_settings, or ::XMR_PRIO_LVL_UNSPEC int8_t nxt_prio; ///< next priority level after holdover, 0..::XMULTI_REF_INSTANCES::n_xmr_settings, or ::XMR_PRIO_LVL_UNSPEC uint8_t remote_watchdog; ///< counts down in ::XMR_HLDOVR_PRE_AUTONOMOUS mode - uint32_t reserved; ///< reserved, don't use, currently 0 + uint32_t time_offset_ns; ///< estimated time offset in holdover operation XMR_HOLDOVER_INTV elapsed; ///< elapsed time in holdover mode, only valid if ::XMR_HLDOVR_MSK_IN_HOLDOVER is set XMR_HOLDOVER_INTV interval; ///< current holdover interval, only valid if ::XMR_HLDOVR_MSK_IN_HOLDOVER is set uint32_t flags; ///< holdover status flags, see ::XMR_HOLDOVER_STATUS_FLAG_MASKS } XMR_HOLDOVER_STATUS; +#define _mbg_swab_xmr_holdover_status( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->mode ); \ + _mbg_swab8( &(_p)->curr_prio ); \ + _mbg_swab8( &(_p)->nxt_prio ); \ + _mbg_swab8( &(_p)->remote_watchdog ); \ + _mbg_swab32( &(_p)->time_offset_ns ); \ + _mbg_swab_xmr_holdover_intv( &(_p)->elapsed ); \ + _mbg_swab_xmr_holdover_intv( &(_p)->interval ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + /** * @brief XMR holdover status modes @@ -5676,9 +7618,9 @@ enum XMR_HOLDOVER_STATUS_MODES */ #define XMR_HOLDOVER_STATUS_MODE_NAMES \ { \ - "autonomous", \ - "pre-autonomous", \ - "remote" \ + "Autonomous", \ + "Pre-Autonomous", \ + "Remote" \ } @@ -5693,6 +7635,7 @@ enum XMR_HOLDOVER_STATUS_FLAG_BITS XMR_HLDOVR_BIT_IN_HOLDOVER, ///< the device is currently in holdover mode XMR_HLDOVR_BIT_TRANSITION_ENBD, ///< timebase is in transition (being slewed) after sources have been switched XMR_HLDOVR_BIT_IN_TRANSITION, ///< transition is currently active, slewing in progress + XMR_HLDOVR_BIT_TIME_OFFS_VALID, ///< values in field ::XMR_HOLDOVER_STATUS::time_offset_ns are valid N_XMR_HOLDOVER_STATUS_FLAG_BITS ///< the number of known status flags }; @@ -5704,18 +7647,375 @@ enum XMR_HOLDOVER_STATUS_FLAG_BITS */ enum XMR_HOLDOVER_STATUS_FLAG_MASKS { - XMR_HLDOVR_MSK_IN_HOLDOVER = ( 1UL << XMR_HLDOVR_BIT_IN_HOLDOVER ), ///< see ::XMR_HLDOVR_BIT_IN_HOLDOVER - XMR_HLDOVR_MSK_TRANSITION_ENBD = ( 1UL << XMR_HLDOVR_BIT_TRANSITION_ENBD ), ///< see ::XMR_HLDOVR_BIT_TRANSITION_ENBD - XMR_HLDOVR_MSK_IN_TRANSITION = ( 1UL << XMR_HLDOVR_BIT_IN_TRANSITION ) ///< see ::XMR_HLDOVR_BIT_IN_TRANSITION + XMR_HLDOVR_MSK_IN_HOLDOVER = ( 1UL << XMR_HLDOVR_BIT_IN_HOLDOVER ), ///< See ::XMR_HLDOVR_BIT_IN_HOLDOVER + XMR_HLDOVR_MSK_TRANSITION_ENBD = ( 1UL << XMR_HLDOVR_BIT_TRANSITION_ENBD ), ///< See ::XMR_HLDOVR_BIT_TRANSITION_ENBD + XMR_HLDOVR_MSK_IN_TRANSITION = ( 1UL << XMR_HLDOVR_BIT_IN_TRANSITION ), ///< See ::XMR_HLDOVR_BIT_IN_TRANSITION + XMR_HLDOVR_MSK_TIME_OFFS_VALID = ( 1UL << XMR_HLDOVR_BIT_TIME_OFFS_VALID ) ///< See ::XMR_HLDOVR_BIT_TIME_OFFS_VALID +}; + + + +/** + * @brief XMR source feature flag bits + * + * Used to define ::XMR_EXT_SRC_FEAT_FLAG_MSKS + */ +enum XMR_EXT_SRC_FEAT_FLAG_BITS +{ + XMR_EXT_SRC_FEAT_FLAG_BIT_STATS, ///< XMR source provides ::XMR_STATS. + XMR_EXT_SRC_FEAT_FLAG_BIT_METRICS, ///< XMR source provides ::XMR_METRICS. + XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING, ///< XMR source supports coasting mode. + XMR_EXT_SRC_FEAT_FLAG_BIT_ADV_METRICS, ///< XMR source supports advanced XMR QL metrics configuration, see ::XMR_QL_LIMITS. + ///< If this feature is not available, ::XMR_METRICS can not be configured. + N_XMR_EXT_SRC_FEAT_FLAG_BITS +}; + + + +/** + * @brief XMR source feature flag bit masks + * + * Used with ::XMR_EXT_SRC_INFO::feat_flags. + * + * @see ::XMR_EXT_SRC_FEAT_FLAG_BITS + */ +enum XMR_EXT_SRC_FEAT_FLAG_MSKS +{ + XMR_EXT_SRC_FEAT_FLAG_MSK_STATS = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_STATS ), ///< See ::XMR_EXT_SRC_FEAT_FLAG_BIT_STATS. + XMR_EXT_SRC_FEAT_FLAG_MSK_METRICS = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_METRICS ), ///< See ::XMR_EXT_SRC_FEAT_FLAG_BIT_METRICS. + XMR_EXT_SRC_FEAT_FLAG_MSK_COASTING = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING ), ///< See ::XMR_EXT_SRC_FEAT_FLAG_BIT_COASTING. + XMR_EXT_SRC_FEAT_FLAG_MSK_ADV_METRICS = ( 1UL << XMR_EXT_SRC_FEAT_FLAG_BIT_ADV_METRICS ) ///< See ::XMR_EXT_SRC_FEAT_FLAG_BIT_ADV_METRICS. +}; + + + +typedef struct +{ + uint16_t supp_flags; ///< Indicates which flags are supported by ::XMULTI_REF_SETTINGS::flags, see ::XMR_SETTINGS_FLAG_MSKS. + uint16_t feat_flags; ///< See ::XMR_EXT_SRC_FEAT_FLAG_MSKS. + uint32_t reserved_0; + +} XMR_EXT_SRC_INFO; + +#define _mbg_swab_xmr_ext_src_info( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->supp_flags ); \ + _mbg_swab16( &(_p)->feat_flags ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ +} while ( 0 ) + + + +typedef struct +{ + uint16_t idx; // + XMR_EXT_SRC_INFO info; // + +} XMR_EXT_SRC_INFO_IDX; // + +#define _mbg_swab_xmr_ext_src_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmr_ext_src_info( &(_p)->info ); \ +} while ( 0 ) + + + +/** + * @brief XMR statistics for a particular source + * + * This structure is only provided by an XMR source which has + * ::XMR_EXT_SRC_FEAT_FLAG_MSK_STATS set in ::XMR_EXT_SRC_INFO::feat_flags. + * + * @see ::XMR_STATS_IDX + * @see ::XMR_EXT_SRC_INFO::feat_flags + * @see ::XMR_EXT_SRC_FEAT_FLAG_MSK_STATS + */ +typedef struct xmr_stats_s +{ + uint32_t timestamp; ///< time stamp when the record was taken, %UTC, seconds since 1970 + NANO_TIME last_mue; ///< mean value (mue) of prev. interval + NANO_TIME last_sigma; ///< standard deviation (sigma) of prev. interval + NANO_TIME last_max; ///< maximum value within interval + NANO_TIME last_min; ///< minimum value within interval + NANO_TIME reserved_0; ///< currently reserved, unused, always 0 + NANO_TIME step_comp_val; ///< current step compensation value + NANO_TIME auto_bias; ///< current time automatic bias compensation + uint32_t reserved_1; ///< currently reserved, unused, always 0 + uint32_t reserved_2; ///< currently reserved, unused, always 0 + uint32_t flags; ///< See ::XMR_STATS_FLAGS_MSKS + +} XMR_STATS; + +#define _mbg_swab_xmr_stats( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->timestamp ); \ + _mbg_swab_nano_time( &(_p)->last_mue ); \ + _mbg_swab_nano_time( &(_p)->last_sigma ); \ + _mbg_swab_nano_time( &(_p)->last_max ); \ + _mbg_swab_nano_time( &(_p)->last_min ); \ + _mbg_swab_nano_time( &(_p)->reserved_0 ); \ + _mbg_swab_nano_time( &(_p)->step_comp_val ); \ + _mbg_swab_nano_time( &(_p)->auto_bias ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of bits used to define ::XMR_STATS_FLAGS_MSKS + * + * @see ::XMR_STATS_FLAGS_MSKS + */ +enum XMR_STATS_FLAGS_BITS +{ + XMR_STATS_FLAG_BIT_STEP_DETECTED, ///< A time step was detected at the input source + XMR_STATS_FLAG_BIT_STEP_COMPENSATED, ///< A time step was compensated at the input source + XMR_STATS_FLAG_BIT_AUTO_BIAS_VALID, ///< The value in ::XMR_STATS::auto_bias is valid + N_XMR_STATS_FLAGS_BITS +}; + + + +/** + * @brief Flag bit masks used with ::XMR_STATS::flags + * + * @see ::XMR_STATS_FLAGS_BITS + */ +enum XMR_STATS_FLAGS_MSKS +{ + XMR_STATS_FLAG_MSK_STEP_DETECTED = ( 1UL << XMR_STATS_FLAG_BIT_STEP_DETECTED ), ///< See ::XMR_STATS_FLAG_BIT_STEP_DETECTED + XMR_STATS_FLAG_MSK_STEP_COMPENSATED = ( 1UL << XMR_STATS_FLAG_BIT_STEP_COMPENSATED ), ///< See ::XMR_STATS_FLAG_BIT_STEP_COMPENSATED + XMR_STATS_FLAG_MSK_AUTO_BIAS_VALID = ( 1UL << XMR_STATS_FLAG_BIT_AUTO_BIAS_VALID ) ///< See ::XMR_STATS_FLAG_BIT_AUTO_BIAS_VALID +}; + + + +/** + * @brief String initializers for XMR Stats Flags + * + * @see ::XMR_STATS_FLAGS_MSKS + */ +#define DEFAULT_XMR_STATS_FLAG_NAMES \ +{ \ + "Step Detected", \ + "Step Compensated", \ + "Auto BIAS valid" \ +} + + + +/** + * @brief XMR statistics for a particular source, with index + * + * @see ::XMR_STATS + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< The priority level index, 0..::XMULTI_REF_INSTANCES::n_xmr_settings-1, 0 == highest. + XMR_STATS stats; ///< XMR statistics of the particular source. + +} XMR_STATS_IDX; + +#define _mbg_swab_xmr_stats_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmr_stats( &(_p)->stats ); \ +} while ( 0 ) + + + +#define MAX_XMR_METRICS 20 + +typedef struct +{ + uint32_t timestamp; + uint32_t flags; ///< idx bit set if mtie[idx] is valid + uint8_t mtie_scale; ///< scale factors of MTIE + uint8_t tdev_scale; ///< scale factors of TDEV + uint16_t reserved_0; ///< currently unused + uint32_t reserved_1; ///< currently unused + uint32_t reserved_2; ///< currently unused + uint32_t mtie[MAX_XMR_METRICS]; ///< mtie scaled 32 bit fixed point unsigned + uint32_t tdev[MAX_XMR_METRICS]; ///< tdev scaled 32 bit fixed point unsigned + +} XMR_METRICS; + +#define _mbg_swab_xmr_metrics( _p ) \ +do \ +{ \ + int i; \ + \ + _mbg_swab32( &(_p)->timestamp ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab8( &(_p)->mtie_scale ); \ + _mbg_swab8( &(_p)->tdev_scale ); \ + _mbg_swab16( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + \ + for ( i = 0; i < MAX_XMR_METRICS; i++ ) \ + _mbg_swab32( &(_p)->mtie[i] ); \ + \ + for ( i = 0; i < MAX_XMR_METRICS; i++ ) \ + _mbg_swab32( &(_p)->tdev[i] ); \ + \ +} while ( 0 ) + + + +// conversion factor scaled FPU32 to double +#define _fpu32_to_double_fac( _x ) ( 1.0 / ( 4294967296.0 * ( _x ) ) ) + + + +/** + * @brief XMR timing metrics for a particular source, with index + * + * @see ::XMR_METRICS + */ +typedef struct +{ + uint16_t idx; + XMR_METRICS metrics; + +} XMR_METRICS_IDX; + +#define _mbg_swab_xmr_metrics_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_xmr_metrics( &(_p)->metrics ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of ITU limit masks + * + * Used for detection of ::XMR_METRICS mask violation. + * + * @see ::ITU_LIMIT_MASKS + * @see ::XMR_METRICS + */ +enum ITU_LIMITS +{ + ITU_LIMIT_NONE, + ITU_LIMIT_G811_PRC, + ITU_LIMIT_G823_SSU, + ITU_LIMIT_G823_SEC, + ITU_LIMIT_G8272_PRTC, + ITU_LIMIT_G82721_EPRTC, + N_ITU_LIMITS +} ; + + + +/** + * @brief Enumeration of ITU limit masks + * + * Used for detection of ::XMR_METRICS mask violation. + * + * @see ::ITU_LIMITS + * @see ::XMR_METRICS + */ +enum ITU_LIMIT_MASKS +{ + MSK_ITU_LIMIT_NONE = ( 1UL << ITU_LIMIT_NONE ), + MSK_ITU_LIMIT_G811_PRC = ( 1UL << ITU_LIMIT_G811_PRC ), + MSK_ITU_LIMIT_G823_SSU = ( 1UL << ITU_LIMIT_G823_SSU ), + MSK_ITU_LIMIT_G823_SEC = ( 1UL << ITU_LIMIT_G823_SEC ), + MSK_ITU_LIMIT_G8272_PRTC = ( 1UL << ITU_LIMIT_G8272_PRTC ), + MSK_ITU_LIMIT_G82721_EPRTC = ( 1UL << ITU_LIMIT_G82721_EPRTC ) }; + +/** + * @brief String initializers for ITU limit masks + * + * Used for detection of ::XMR_METRICS mask violation. + * + * @see ::ITU_LIMITS + * @see ::XMR_METRICS + */ +#define ITU_LIMIT_SHORT_STRS \ +{ \ + "None", \ + "G811 (PRC)", \ + "G823 (SSU)", \ + "G823 (SEC)", \ + "G8272 (PRTC)", \ + "G82721 (ePRTC)" \ +} + + + +/** + * @brief Supported limits for qualtity metrics + * + * @see ::XMR_METRICS + */ +typedef struct +{ + uint32_t supp_ql_masks; ///< see :ITU_LIMIT_MASKS. Masks apply to all sources! + uint32_t reserved_0; + uint32_t reserved_1; + uint32_t reserved_2; + +} XMR_QL_LIMITS; + +#define _mbg_swab_xmr_ql_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_ql_masks ); \ +} while ( 0 ) + + + +typedef struct +{ + uint8_t ql_mask; ///< see :ITU_LIMIT_MASKS + uint8_t hysteresis; ///< hysteresis (percent) between yellow and red alarm + uint16_t reserved_0; + uint32_t reserved_1; + +} XMR_QL_SETTINGS; + +#define _mbg_swab_xmr_ql_settings( _p ) \ +do \ +{ \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t idx; + XMR_QL_SETTINGS settings; + +} XMR_QL_SETTINGS_IDX; + +#define _mbg_swab_xmr_ql_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_xmr_ql_settings( &(_p)->settings ); \ +} while ( 0 ) + + + /** @} defgroup group_multi_ref_ext */ /** @} defgroup group_multi_ref_all */ - /** * @defgroup group_gpio GPIO port configuration stuff * @@ -5737,21 +8037,22 @@ typedef struct { uint32_t num_io; ///< number of supported GPIO ports uint32_t reserved; ///< reserved, currently always 0 - uint32_t flags; ///< see ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS + uint32_t flags; ///< See ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS } MBG_GPIO_CFG_LIMITS; -#define _mbg_swab_gpio_cfg_limits( p ) \ -{ \ - _mbg_swab32( &(_p)->num_io ); \ - _mbg_swab32( &(_p)->reserved ); \ - _mbg_swab32( &(_p)->flags ); \ -} +#define _mbg_swab_mbg_gpio_cfg_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->num_io ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) /** - * @brief GPIO limits flag bits uded to define ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS + * @brief GPIO limits flag bits used to define ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS * * @see ::MBG_GPIO_CFG_LIMIT_FLAG_MASKS */ @@ -5772,7 +8073,7 @@ enum MBG_GPIO_CFG_LIMIT_FLAG_BITS */ enum MBG_GPIO_CFG_LIMIT_FLAG_MASKS { - MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP = ( 1UL << MBG_GPIO_CFG_LIMIT_FLAG_BIT_STATUS_SUPP ), ///< see ::MBG_GPIO_CFG_LIMIT_FLAG_BIT_STATUS_SUPP + MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP = ( 1UL << MBG_GPIO_CFG_LIMIT_FLAG_BIT_STATUS_SUPP ), ///< See ::MBG_GPIO_CFG_LIMIT_FLAG_BIT_STATUS_SUPP }; @@ -5789,22 +8090,35 @@ enum MBG_GPIO_CFG_LIMIT_FLAG_MASKS */ enum MBG_GPIO_TYPES { - MBG_GPIO_TYPE_FREQ_IN, ///< variable frequency input, freq == 0 if input not used - MBG_GPIO_TYPE_FREQ_OUT, ///< variable frequency output - MBG_GPIO_TYPE_FIXED_FREQ_OUT, ///< fixed frequency output - MBG_GPIO_TYPE_BITS_IN, ///< framed data stream input - MBG_GPIO_TYPE_BITS_OUT, ///< framed data stream output - N_MBG_GPIO_TYPES ///< number of known types + MBG_GPIO_TYPE_FREQ_IN, ///< Variable frequency input, freq == 0 if input not used + MBG_GPIO_TYPE_FREQ_OUT, ///< Variable frequency output + MBG_GPIO_TYPE_FIXED_FREQ_OUT, ///< Fixed frequency output + MBG_GPIO_TYPE_BITS_IN, ///< Framed data stream input + MBG_GPIO_TYPE_BITS_OUT, ///< Framed data stream output + MBG_GPIO_TYPE_VIDEO_OUT, ///< Video signal output (PAL, NTSC, ...) + MBG_GPIO_TYPE_VIDEO_SYNC_OUT, ///< Video sync signal output (H-Sync, V-Sync, ...) + MBG_GPIO_TYPE_STUDIO_CLOCK_OUT, ///< Studio clock output + MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT, ///< Digital Audio output (DARS, ...) + MBG_GPIO_TYPE_VIDEO_IN, ///< Video signal output (PAL, NTSC, ...) + MBG_GPIO_TYPE_LTC_OUT, ///< Linear Timecode output + N_MBG_GPIO_TYPES ///< Number of known types }; + #define DEFAULT_GPIO_TYPES_SHORT_STRS \ { \ "Freq. In", \ "Freq. Out", \ "Fixed Freq Out", \ "BITS In", \ - "BITS Out" \ + "BITS Out", \ + "Video Out", \ + "Video Sync Out", \ + "Studio Clock Out", \ + "Digital Audio Out", \ + "Video In", \ + "LTC Out" \ } @@ -5827,6 +8141,7 @@ enum MBG_GPIO_SIGNAL_SHAPES }; + /** * @brief Bit masks associated with ::MBG_GPIO_SIGNAL_SHAPES * @@ -5838,9 +8153,9 @@ enum MBG_GPIO_SIGNAL_SHAPES */ enum MBG_GPIO_SIGNAL_SHAPE_MASKS { - MBG_GPIO_SIGNAL_SHAPE_MSK_UNSPECIFIED = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED ), ///< see ::MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED - MBG_GPIO_SIGNAL_SHAPE_MSK_SINE = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SINE ), ///< see ::MBG_GPIO_SIGNAL_SHAPE_SINE - MBG_GPIO_SIGNAL_SHAPE_MSK_SQUARE = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SQUARE ) ///< see ::MBG_GPIO_SIGNAL_SHAPE_SQUARE + MBG_GPIO_SIGNAL_SHAPE_MSK_UNSPECIFIED = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED ), ///< See ::MBG_GPIO_SIGNAL_SHAPE_UNSPECIFIED + MBG_GPIO_SIGNAL_SHAPE_MSK_SINE = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SINE ), ///< See ::MBG_GPIO_SIGNAL_SHAPE_SINE + MBG_GPIO_SIGNAL_SHAPE_MSK_SQUARE = ( 1UL << MBG_GPIO_SIGNAL_SHAPE_SQUARE ) ///< See ::MBG_GPIO_SIGNAL_SHAPE_SQUARE }; @@ -5854,7 +8169,7 @@ enum MBG_GPIO_SIGNAL_SHAPE_MASKS { \ "(unspec. shape)", \ "Sine wave", \ - "Rectangle Pulse" \ + "Rectangle pulse" \ } @@ -5871,6 +8186,13 @@ typedef struct } MBG_GPIO_FREQ; +#define _mbg_swab_mbg_gpio_freq( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->hz ); \ + _mbg_swab32( &(_p)->frac); \ +} while ( 0 ) + /** @@ -5891,6 +8213,17 @@ typedef struct } MBG_GPIO_FREQ_IN_SETTINGS; +#define _mbg_swab_mbg_gpio_freq_in_settings( _p ) \ +do \ +{ \ + _mbg_swab_mbg_gpio_freq( &(_p)->freq ); \ + _mbg_swab32( &(_p)->csc_limit ); \ + _mbg_swab32( &(_p)->shape ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + /** * @brief Supported options for a variable frequency GPIO input @@ -5906,11 +8239,22 @@ typedef struct uint32_t freq_max; ///< maximum output frequency [Hz] uint32_t csc_limit_max; ///< 1/1000 units of the signal period, limited due to 10 ns sampling interval, see ::MBG_GPIO_FREQ_IN_SETTINGS::csc_limit //##++++++++++++++++ uint32_t supp_shapes; ///< bit mask of supported signal shapes, see ::MBG_GPIO_SIGNAL_SHAPE_MASKS - uint32_t reserved; ///< reserved, currently always 0 + uint32_t supp_limits; ///< supported ITU limit masks for BITS signal see ::ITU_LIMIT_MASKS uint32_t flags; ///< reserved, currently always 0 } MBG_GPIO_FREQ_IN_SUPP; +#define _mbg_swab_mbg_gpio_freq_in_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->freq_min ); \ + _mbg_swab32( &(_p)->freq_max ); \ + _mbg_swab32( &(_p)->csc_limit_max ); \ + _mbg_swab32( &(_p)->supp_shapes ); \ + _mbg_swab32( &(_p)->supp_limits ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + /** @@ -5931,6 +8275,16 @@ typedef struct } MBG_GPIO_FREQ_OUT_SETTINGS; +#define _mbg_swab_mbg_gpio_freq_out_settings( _p ) \ +do \ +{ \ + _mbg_swab_mbg_gpio_freq( &(_p)->freq ); \ + _mbg_swab32( &(_p)->milli_phase ); \ + _mbg_swab32( &(_p)->shape ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + /** @@ -5953,6 +8307,18 @@ typedef struct } MBG_GPIO_FREQ_OUT_SUPP; +#define _mbg_swab_mbg_gpio_freq_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->freq_min ); \ + _mbg_swab32( &(_p)->freq_max ); \ + _mbg_swab32( &(_p)->freq_resolution ); \ + _mbg_swab32( &(_p)->milli_phase_max ); \ + _mbg_swab32( &(_p)->supp_shapes ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + /** @@ -5974,6 +8340,7 @@ enum MBG_GPIO_FIXED_FREQS N_MBG_GPIO_FIXED_FREQ ///< number of predefined fixed frequencies }; + /** * @brief Bit masks associated with ::MBG_GPIO_FIXED_FREQS * @@ -5982,14 +8349,14 @@ enum MBG_GPIO_FIXED_FREQS */ enum MBG_GPIO_FIXED_FREQ_MASKS { - MSK_MBG_GPIO_FIXED_FREQ_8kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_8kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_8kHz - MSK_MBG_GPIO_FIXED_FREQ_48kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_48kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_48kHz - MSK_MBG_GPIO_FIXED_FREQ_1MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_1MHz ), ///< see ::MBG_GPIO_FIXED_FREQ_1MHz - MSK_MBG_GPIO_FIXED_FREQ_1544kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_1544kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_1544kHz - MSK_MBG_GPIO_FIXED_FREQ_2048kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_2048kHz ), ///< see ::MBG_GPIO_FIXED_FREQ_2048kHz - MSK_MBG_GPIO_FIXED_FREQ_5MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_5MHz ), ///< see ::MBG_GPIO_FIXED_FREQ_5MHz - MSK_MBG_GPIO_FIXED_FREQ_10MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_10MHz ), ///< see ::MBG_GPIO_FIXED_FREQ_10MHz - MSK_MBG_GPIO_FIXED_FREQ_19440kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_19440kHz ) ///< see ::MBG_GPIO_FIXED_FREQ_19440kHz + MSK_MBG_GPIO_FIXED_FREQ_8kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_8kHz ), ///< See ::MBG_GPIO_FIXED_FREQ_8kHz + MSK_MBG_GPIO_FIXED_FREQ_48kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_48kHz ), ///< See ::MBG_GPIO_FIXED_FREQ_48kHz + MSK_MBG_GPIO_FIXED_FREQ_1MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_1MHz ), ///< See ::MBG_GPIO_FIXED_FREQ_1MHz + MSK_MBG_GPIO_FIXED_FREQ_1544kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_1544kHz ), ///< See ::MBG_GPIO_FIXED_FREQ_1544kHz + MSK_MBG_GPIO_FIXED_FREQ_2048kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_2048kHz ), ///< See ::MBG_GPIO_FIXED_FREQ_2048kHz + MSK_MBG_GPIO_FIXED_FREQ_5MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_5MHz ), ///< See ::MBG_GPIO_FIXED_FREQ_5MHz + MSK_MBG_GPIO_FIXED_FREQ_10MHz = ( 1UL << MBG_GPIO_FIXED_FREQ_10MHz ), ///< See ::MBG_GPIO_FIXED_FREQ_10MHz + MSK_MBG_GPIO_FIXED_FREQ_19440kHz = ( 1UL << MBG_GPIO_FIXED_FREQ_19440kHz ) ///< See ::MBG_GPIO_FIXED_FREQ_19440kHz }; @@ -6012,6 +8379,7 @@ enum MBG_GPIO_FIXED_FREQ_MASKS } + /** * @brief Configuration of a GPIO fixed frequency output * @@ -6029,6 +8397,16 @@ typedef struct } MBG_GPIO_FIXED_FREQ_OUT_SETTINGS; +#define _mbg_swab_mbg_gpio_fixed_freq_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->freq_idx ); \ + _mbg_swab32( &(_p)->shape ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + /** * @brief Supported options for a fixed frequency output @@ -6047,6 +8425,15 @@ typedef struct } MBG_GPIO_FIXED_FREQ_OUT_SUPP; +#define _mbg_swab_mbg_gpio_fixed_freq_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_freq ); \ + _mbg_swab32( &(_p)->supp_shapes ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + /** @@ -6065,6 +8452,7 @@ enum MBG_GPIO_BITS_FORMATS N_MBG_GPIO_BITS_FORMATS ///< number of defined formats }; + /** * @brief Bit masks associated with ::MBG_GPIO_BITS_FORMATS * @@ -6074,13 +8462,28 @@ enum MBG_GPIO_BITS_FORMATS */ enum MBG_GPIO_BITS_FORMAT_MASKS { - MSK_MBG_GPIO_BITS_E1_FRAMED = ( 1UL << MBG_GPIO_BITS_E1_FRAMED ), ///< see ::MBG_GPIO_BITS_E1_FRAMED - MSK_MBG_GPIO_BITS_T1_FRAMED = ( 1UL << MBG_GPIO_BITS_T1_FRAMED ), ///< see ::MBG_GPIO_BITS_T1_FRAMED - MSK_MBG_GPIO_BITS_E1_TIMING = ( 1UL << MBG_GPIO_BITS_E1_TIMING ), ///< see ::MBG_GPIO_BITS_E1_TIMING - MSK_MBG_GPIO_BITS_T1_TIMING = ( 1UL << MBG_GPIO_BITS_T1_TIMING ) ///< see ::MBG_GPIO_BITS_T1_TIMING + MSK_MBG_GPIO_BITS_E1_FRAMED = ( 1UL << MBG_GPIO_BITS_E1_FRAMED ), ///< See ::MBG_GPIO_BITS_E1_FRAMED + MSK_MBG_GPIO_BITS_T1_FRAMED = ( 1UL << MBG_GPIO_BITS_T1_FRAMED ), ///< See ::MBG_GPIO_BITS_T1_FRAMED + MSK_MBG_GPIO_BITS_E1_TIMING = ( 1UL << MBG_GPIO_BITS_E1_TIMING ), ///< See ::MBG_GPIO_BITS_E1_TIMING + MSK_MBG_GPIO_BITS_T1_TIMING = ( 1UL << MBG_GPIO_BITS_T1_TIMING ) ///< See ::MBG_GPIO_BITS_T1_TIMING }; +/** + * @brief Initializers for an array of GPIO bit format strings + * + * @see ::MBG_GPIO_BITS_FORMATS + * @see ::MBG_GPIO_BITS_FORMAT_MASKS + */ +#define MBG_GPIO_BITS_FORMAT_STRS \ +{ \ + "E1 Framed", \ + "T1 Framed", \ + "E1 Timing", \ + "T1 Timing" \ +} + + /** * @brief Minimum and maximum known SSM values @@ -6126,6 +8529,7 @@ enum GPIO_SA_BITS_GROUPS }; + /** * @brief Configuration of a GPIO as BITS input module * @@ -6136,9 +8540,9 @@ enum GPIO_SA_BITS_GROUPS */ typedef struct { - uint32_t format; ///< signal format, see ::MBG_GPIO_BITS_FORMATS - uint32_t reserved; ///< reserved, currently always 0 - uint32_t csc_limit; ///< max. cycle slip [1/1000 cycle units] + uint32_t format; ///< signal format, see ::MBG_GPIO_BITS_FORMATS + uint32_t reserved; ///< reserved, currently always 0 + uint32_t csc_limit; ///< max. cycle slip [1/1000 cycle units] union quality { @@ -6165,6 +8569,38 @@ typedef struct } MBG_GPIO_BITS_IN_SETTINGS; +#define _mbg_swab_mbg_gpio_bits_in_settings( _p, _recv ) \ +do \ +{ \ + uint32_t f = (_p)->format; \ + if ( (_recv) ) \ + _mbg_swab32( &f); \ + _mbg_swab32( &(_p)->format ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->csc_limit ); \ + switch( f ) \ + { \ + case MBG_GPIO_BITS_E1_FRAMED : \ + case MBG_GPIO_BITS_E1_TIMING : \ + _mbg_swab8( &(_p)->quality.e1.ssm ); \ + _mbg_swab8( &(_p)->quality.e1.sa_bits ); \ + _mbg_swab16( &(_p)->quality.e1.reserved ); \ + break; \ + \ + case MBG_GPIO_BITS_T1_FRAMED : \ + case MBG_GPIO_BITS_T1_TIMING : \ + _mbg_swab8( &(_p)->quality.t1.min_boc ); \ + _mbg_swab8( &(_p)->quality.t1.reserved_0 ); \ + _mbg_swab16( &(_p)->quality.t1.reserved_1 ); \ + break; \ + \ + default: \ + break; \ + } \ + _mbg_swab32( &(_p)->err_msk ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + /** @@ -6177,6 +8613,7 @@ enum MBG_GPIO_BITS_ERRS N_MBG_GPIO_BITS_ERRS ///< number of known errors }; + /** * @brief Bit masks associated with BITS input error conditions * @@ -6186,11 +8623,12 @@ enum MBG_GPIO_BITS_ERRS */ enum MBG_GPIO_BITS_ERR_MASKS { - MSK_MBG_GPIO_BITS_ERR_LOS = ( 1UL << MBG_GPIO_BITS_ERR_LOS ), ///< see ::MBG_GPIO_BITS_ERR_LOS - MSK_MBG_GPIO_BITS_ERR_LOF = ( 1UL << MBG_GPIO_BITS_ERR_LOF ) ///< see ::MBG_GPIO_BITS_ERR_LOF + MSK_MBG_GPIO_BITS_ERR_LOS = ( 1UL << MBG_GPIO_BITS_ERR_LOS ), ///< See ::MBG_GPIO_BITS_ERR_LOS + MSK_MBG_GPIO_BITS_ERR_LOF = ( 1UL << MBG_GPIO_BITS_ERR_LOF ) ///< See ::MBG_GPIO_BITS_ERR_LOF }; + /** * @brief Supported options of a BITS GPIO input * @@ -6201,11 +8639,18 @@ enum MBG_GPIO_BITS_ERR_MASKS */ typedef struct { - uint32_t supp_fmts; ///< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMAT_MASKS - uint32_t reserved; ///< reserved, currently always 0 + uint32_t supp_fmts; ///< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMAT_MASKS + uint32_t reserved; ///< reserved, currently always 0 } MBG_GPIO_BITS_IN_SUPP; +#define _mbg_swab_mbg_gpio_bits_in_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_fmts ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + /** @@ -6230,9 +8675,27 @@ typedef struct } MBG_GPIO_BITS_OUT_SETTINGS; +#define _mbg_swab_mbg_gpio_bits_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->format ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab8( &(_p)->sa_bits ); \ + _mbg_swab8( &(_p)->ssm ); \ + _mbg_swab8( &(_p)->boc ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + /** * @brief Enumeration of flags used with BITS type GPIO outputs + * + * @see ::MBG_GPIO_BITS_OUT_FLAG_MASKS + * @see ::MBG_GPIO_BITS_OUT_FLAG_STRS */ enum MBG_GPIO_BITS_OUT_FLAGS { @@ -6241,21 +8704,36 @@ enum MBG_GPIO_BITS_OUT_FLAGS N_MBG_GPIO_BITS_OUT_FLAGS ///< number of known flags }; + /** * @brief Bit masks associated with ::MBG_GPIO_BITS_OUT_FLAGS * * Used with ::MBG_GPIO_BITS_OUT_SETTINGS::flags * * @see ::MBG_GPIO_BITS_OUT_FLAGS + * @see ::MBG_GPIO_BITS_OUT_FLAG_STRS */ enum MBG_GPIO_BITS_OUT_FLAG_MASKS { - MSK_MBG_GPIO_BITS_OUT_FLAG_HDB3 = ( 1UL << MBG_GPIO_BITS_OUT_FLAG_HDB3 ), ///< see ::MBG_GPIO_BITS_OUT_FLAG_HDB3 - MSK_MBG_GPIO_BITS_OUT_FLAG_B8ZS = ( 1UL << MBG_GPIO_BITS_OUT_FLAG_B8ZS ) ///< see ::MBG_GPIO_BITS_OUT_FLAG_B8ZS + MSK_MBG_GPIO_BITS_OUT_FLAG_HDB3 = ( 1UL << MBG_GPIO_BITS_OUT_FLAG_HDB3 ), ///< See ::MBG_GPIO_BITS_OUT_FLAG_HDB3 + MSK_MBG_GPIO_BITS_OUT_FLAG_B8ZS = ( 1UL << MBG_GPIO_BITS_OUT_FLAG_B8ZS ) ///< See ::MBG_GPIO_BITS_OUT_FLAG_B8ZS }; /** + * @brief String initializers for an array of GPIO BITS out flags + * + * @see ::MBG_GPIO_BITS_OUT_FLAGS + * @see ::MBG_GPIO_BITS_OUT_FLAG_MASKS + */ +#define MBG_GPIO_BITS_OUT_FLAG_STRS \ +{ \ + "HDB3", \ + "B8ZS" \ +} + + +/** * @brief Supported options of a BITS type GPIO output * * Used as sub-structure of ::MBG_GPIO_LIMITS. @@ -6265,93 +8743,1251 @@ enum MBG_GPIO_BITS_OUT_FLAG_MASKS */ typedef struct { - uint32_t supp_fmts; ///< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMAT_MASKS - uint32_t reserved; ///< reserved, currently always 0 + uint32_t supp_fmts; ///< bit mask of supported formats, see ::MBG_GPIO_BITS_FORMAT_MASKS + uint32_t supp_flags; ///< bit mask of supported flags, see ::MBG_GPIO_BITS_OUT_FLAG_MASKS } MBG_GPIO_BITS_OUT_SUPP; +#define _mbg_swab_mbg_gpio_bits_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_fmts ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + /** - * @brief A generic structure used to hold a GPIO port's settings + * @brief Enumeration of Video signal formats + * + * Used with ::MBG_GPIO_VIDEO_OUT_SETTINGS::format + * + * @see ::MBG_GPIO_VIDEO_FORMAT_MASKS + */ +enum MBG_GPIO_VIDEO_FORMATS +{ + MBG_GPIO_VIDEO_FORMAT_OFF, ///< OFF + MBG_GPIO_VIDEO_SD_FORMAT_NTSC, ///< NTSC 525i + MBG_GPIO_VIDEO_SD_FORMAT_PAL, ///< PAL standard (Germany) 625i + MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz, ///< SMPTE296M-3 720p at 50 Hz + MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz, ///< SMPTE274M-6 1080i at 50 Hz + MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz, ///< SMPTE296M-1 720p at 59.94 Hz + MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz, ///< SMPTE274M-7 1080i at 59.94 Hz + MBG_GPIO_VIDEO_SD_FORMAT_PAL_M, ///< PAL M (Brazil) 525i + N_MBG_GPIO_VIDEO_FORMATS ///< number of defined video formats +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_FORMATS + * + * Used with ::MBG_GPIO_VIDEO_OUT_SUPP::supp_formats + * + * @see ::MBG_GPIO_VIDEO_FORMATS + */ +enum MBG_GPIO_VIDEO_FORMAT_MASKS +{ + MSK_MBG_GPIO_VIDEO_FORMAT_OFF = ( 1UL << MBG_GPIO_VIDEO_FORMAT_OFF ), ///< See ::MBG_GPIO_VIDEO_FORMAT_OFF + MSK_MBG_GPIO_VIDEO_SD_FORMAT_NTSC = ( 1UL << MBG_GPIO_VIDEO_SD_FORMAT_NTSC ), ///< See ::MBG_GPIO_VIDEO_SD_FORMAT_NTSC + MSK_MBG_GPIO_VIDEO_SD_FORMAT_PAL = ( 1UL << MBG_GPIO_VIDEO_SD_FORMAT_PAL ), ///< See ::MBG_GPIO_VIDEO_SD_FORMAT_PAL + MSK_MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz ), ///< See ::MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz + MSK_MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz ), ///< See ::MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz + MSK_MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz ), ///< See ::MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz + MSK_MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz = ( 1UL << MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz ), ///< See ::MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz + MSK_MBG_GPIO_VIDEO_SD_FORMAT_PAL_M = ( 1UL << MBG_GPIO_VIDEO_SD_FORMAT_PAL_M ) ///< See ::MBG_GPIO_VIDEO_SD_FORMAT_PAL_M +}; + + +/** + * @brief A combination of bit masks for SD video formats + * @see ::MBG_GPIO_VIDEO_FORMAT_MASKS + */ +#define MBG_GPIO_VIDEO_SD_FORMATS ( MSK_MBG_GPIO_VIDEO_FORMAT_OFF | MSK_MBG_GPIO_VIDEO_SD_FORMAT_NTSC | MSK_MBG_GPIO_VIDEO_SD_FORMAT_PAL | \ + MSK_MBG_GPIO_VIDEO_SD_FORMAT_PAL_M ) + +/** + * @brief A combination of bit masks for HD video formats + * @see ::MBG_GPIO_VIDEO_FORMAT_MASKS + */ +#define MBG_GPIO_VIDEO_HD_FORMATS ( MSK_MBG_GPIO_VIDEO_FORMAT_OFF | MSK_MBG_GPIO_VIDEO_HD_FORMAT_720_P_50Hz | MSK_MBG_GPIO_VIDEO_HD_FORMAT_1080_I_50Hz | \ + MSK_MBG_GPIO_VIDEO_HD_FORMAT_720_P_59_94Hz | MSK_MBG_GPIO_VIDEO_HD_FORMAT_1080_I_59_94Hz ) + + + +/** + * @brief Initializers for an array of video format strings + * + * @see ::MBG_GPIO_VIDEO_FORMATS + * @see ::MBG_GPIO_VIDEO_FORMAT_MASKS + */ +#define MBG_GPIO_VIDEO_FORMAT_STRS \ +{ \ + "OFF", \ + "NTSC (525i)", \ + "PAL (625i)", \ + "720p 50 Hz", \ + "1080i 50 Hz", \ + "720p 59.94 Hz", \ + "1080i 59.94 Hz", \ + "PAL M (525i)" \ +} + + + +/** + * @brief Enumeration of flags used with video type GPIO outputs + */ +enum MBG_GPIO_VIDEO_OUT_FLAGS +{ + MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF, ///< if set, Out1: HD, Out2: SD + MBG_GPIO_VIDEO_OUT_HAS_TC_SD, ///< supports Time Code for SD Black Bursts + N_MBG_GPIO_VIDEO_OUT_FLAGS ///< number of known flags +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_OUT_FLAGS + * + * Used with ::MBG_GPIO_VIDEO_OUT_SETTINGS::flags + * + * @see ::MBG_GPIO_VIDEO_OUT_FLAGS + */ +enum MBG_GPIO_VIDEO_OUT_FLAG_MASKS +{ + MSK_MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF = ( 1UL << MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF ), ///< See ::MBG_GPIO_VIDEO_OUT_HAS_NO_FREE_CONF + MSK_MBG_GPIO_VIDEO_OUT_HAS_TC_SD = ( 1UL << MBG_GPIO_VIDEO_OUT_HAS_TC_SD ) ///< See ::MBG_GPIO_VIDEO_OUT_HAS_TC_SD +}; + + + +/** + * @brief Enumeration of epochs used with video type GPIO outputs + * + * Used with ::MBG_GPIO_VIDEO_OUT_SETTINGS::epoch, and used to + * define ::MBG_GPIO_VIDEO_EPOCH_MASKS + * + * @see ::MBG_GPIO_VIDEO_EPOCH_MASKS + * @see ::MBG_GPIO_VIDEO_EPOCH_STRS + */ +enum MBG_GPIO_VIDEO_EPOCHS +{ + SMPTE_TAI_EPOCH_1970, ///< 1970-01-01 00:00:00 + SMPTE_TAI_EPOCH_1958, ///< 1958-01-01 00:00:00 + SMPTE_UTC_EPOCH_1972, ///< 1972-01-01 00:00:00 + SMPTE_GPS_EPOCH_1980, ///< 1980-01-06 00:00:00 + N_MBG_GPIO_VIDEO_EPOCHS ///< number of known epochs +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_EPOCHS + * + * Used with :: MBG_GPIO_VIDEO_OUT_SUPP::supp_epochs + * + * @see ::MBG_GPIO_VIDEO_EPOCHS + */ +enum MBG_GPIO_VIDEO_EPOCH_MASKS +{ + MSK_SMPTE_TAI_EPOCH_1970 = ( 1UL << SMPTE_TAI_EPOCH_1970 ), ///< See ::SMPTE_TAI_EPOCH_1970 + MSK_SMPTE_TAI_EPOCH_1958 = ( 1UL << SMPTE_TAI_EPOCH_1958 ), ///< See ::SMPTE_TAI_EPOCH_1958 + MSK_SMPTE_UTC_EPOCH_1972 = ( 1UL << SMPTE_UTC_EPOCH_1972 ), ///< See ::SMPTE_UTC_EPOCH_1972 + MSK_SMPTE_GPS_EPOCH_1980 = ( 1UL << SMPTE_GPS_EPOCH_1980 ) ///< See ::SMPTE_GPS_EPOCH_1980 +}; + + + +/** + * @brief Initializers for an array of video epoch strings + * + * @see ::MBG_GPIO_VIDEO_EPOCHS + */ +#define MBG_GPIO_VIDEO_EPOCH_STRS \ +{ \ + "TAI D1970-01-01 T00:00:00", \ + "TAI D1958-01-01 T00:00:00", \ + "UTC D1972-01-01 T00:00:00", \ + "GPS D1980-01-06 T00:00:00" \ +} + + + +/** + * @brief Enumeration of time code modes used with video type GPIO outputs + * + * Used with ::MBG_GPIO_VIDEO_OUT_SETTINGS::tc_mode + * + */ +enum MBG_GPIO_VIDEO_TC_MODES +{ + MBG_GPIO_VIDEO_TC_MODE_NONE, ///< None + MBG_GPIO_VIDEO_TC_MODE_VITC, ///< Vertical Interval Time Code + N_MBG_GPIO_VIDEO_TC_MODES +}; + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_TC_MODES + * + * Used with ::MBG_GPIO_VIDEO_OUT_SETTINGS::tc_mode + * + */ +enum MBG_GPIO_VIDEO_TC_MODE_MASKS +{ + MSK_MBG_GPIO_VIDEO_TC_MODE_NONE = ( 1UL << MBG_GPIO_VIDEO_TC_MODE_NONE ), ///< See ::MBG_GPIO_VIDEO_TC_MODE_NONE + MSK_MBG_GPIO_VIDEO_TC_MODE_VITC = ( 1UL << MBG_GPIO_VIDEO_TC_MODE_VITC ) ///< See ::MBG_GPIO_VIDEO_TC_MODE_VITC +}; + + +/** + * @brief Initializers for an array of video time code modes + * + * @see ::MBG_GPIO_VIDEO_TC_MODES + */ +#define MBG_GPIO_VIDEO_TC_MODE_STRS \ +{ \ + "None", \ + "VITC" \ +} + + + +/** + * @brief Configuration of a GPIO as video output module + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_VIDEO_OUT + * @see ::MBG_GPIO_SETTINGS */ typedef struct { - uint32_t type; ///< GPIO type, see ::MBG_GPIO_TYPES - uint32_t reserved; ///< reserved, currently always 0 - uint32_t flags; ///< reserved, currently always 0 + uint32_t format; ///< video format, see ::MBG_GPIO_VIDEO_FORMATS + uint32_t flags; ///< flags, see ::MBG_GPIO_VIDEO_OUT_FLAG_MASKS + int32_t phase_offset; ///< Phase offset in [ns] + uint8_t epoch; ///< epoch, see ::MBG_GPIO_VIDEO_EPOCHS + + uint8_t tc_mode; ///< time code mode, see ::MBG_GPIO_VIDEO_TC_MODES + uint8_t tc_line0; ///< first time code line location, valid lines: 6-22 + uint8_t tc_line1; ///< second time code line location, valid lines: 6-22 + + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + +} MBG_GPIO_VIDEO_OUT_SETTINGS; + +#define _mbg_swab_mbg_gpio_video_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->format ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->phase_offset ); \ + _mbg_swab8( &(_p)->epoch ); \ + _mbg_swab8( &(_p)->tc_mode ); \ + _mbg_swab8( &(_p)->tc_line0 ); \ + _mbg_swab8( &(_p)->tc_line1 ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ +} while ( 0 ) + + + +/** + * @brief Supported options of a video type GPIO output + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_VIDEO_OUT + * @see ::MBG_GPIO_LIMITS + */ +typedef struct +{ + uint32_t supp_formats; ///< supported video formats, see ::MBG_GPIO_VIDEO_FORMAT_MASKS + uint32_t supp_flags; ///< supported flags, see ::MBG_GPIO_VIDEO_OUT_FLAG_MASKS + uint32_t supp_epochs; ///< supported epochs, see ::MBG_GPIO_VIDEO_EPOCH_MASKS + + uint8_t supp_tc_modes; ///< supported tc_modes, see ::MBG_GPIO_VIDEO_TC_MODE_MASKS + + uint8_t reserved0; ///< reserved, currently always 0 + uint8_t reserved2; ///< reserved, currently always 0 + uint16_t reserved3; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + +} MBG_GPIO_VIDEO_OUT_SUPP; + +#define _mbg_swab_mbg_gpio_video_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_formats ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->supp_epochs ); \ + _mbg_swab8( &(_p)->supp_tc_modes ); \ + _mbg_swab8( &(_p)->reserved0 ); \ + _mbg_swab16( &(_p)->reserved2 ); \ + _mbg_swab16( &(_p)->reserved3 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of types used with video sync GPIO outputs + * Depends on configured video output + */ +enum MBG_GPIO_VIDEO_SYNC_TYPES +{ + MBG_GPIO_VIDEO_SYNC_TYPE_OFF, ///< Output Off + MBG_GPIO_VIDEO_SYNC_TYPE_SD_HSYNC, ///< SD horizontal sync + MBG_GPIO_VIDEO_SYNC_TYPE_SD_VSYNC, ///< SD vertical sync + MBG_GPIO_VIDEO_SYNC_TYPE_SD_FRAME, ///< SD frame/field sync + MBG_GPIO_VIDEO_SYNC_TYPE_SD_BLANK, ///< SD blanking interval + MBG_GPIO_VIDEO_SYNC_TYPE_HD_HSYNC, ///< HD horizontal sync + MBG_GPIO_VIDEO_SYNC_TYPE_HD_VSYNC, ///< HD vertical sync + MBG_GPIO_VIDEO_SYNC_TYPE_HD_FRAME, ///< HD frame/field sync + MBG_GPIO_VIDEO_SYNC_TYPE_HD_BLANK, ///< HD blanking interval + N_MBG_GPIO_VIDEO_SYNC_TYPES ///< number of known types +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_SYNC_TYPES + * + * Used with ::MBG_GPIO_VIDEO_SYNC_OUT_SUPP::supp_types + * + * @see ::MBG_GPIO_VIDEO_SYNC_TYPES + */ +enum MBG_GPIO_VIDEO_SYNC_TYPE_MASKS +{ + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_OFF = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_OFF ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_HSYNC = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_SD_HSYNC ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_VSYNC = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_SD_VSYNC ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_FRAME = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_SD_FRAME ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_BLANK = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_SD_BLANK ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_HSYNC = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_HD_HSYNC ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_VSYNC = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_HD_VSYNC ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_FRAME = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_HD_FRAME ), + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_BLANK = ( 1UL << MBG_GPIO_VIDEO_SYNC_TYPE_HD_BLANK ) +}; + + + +/** + * @brief Initializers for an array of video sync output name strings + * + * @see ::MBG_GPIO_VIDEO_SYNC_TYPES + * @see ::MBG_GPIO_VIDEO_SYNC_TYPE_MASKS + */ +#define MBG_GPIO_VIDEO_SYNC_OUT_STRS \ +{ \ + "OFF", \ + "SD H-Sync", \ + "SD V-Sync", \ + "SD Frame", \ + "SD Blank", \ + "HD H-Sync", \ + "HD V-Sync", \ + "HD Frame", \ + "HD Blank" \ +} + + + +/** + * @brief A combination of bit masks for SD video sync types + * @see ::MBG_GPIO_VIDEO_SYNC_TYPE_MASKS + */ +#define MBG_GPIO_VIDEO_SYNC_SD_TYPES ( MSK_MBG_GPIO_VIDEO_SYNC_TYPE_OFF | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_HSYNC | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_VSYNC | \ + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_FRAME | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_SD_BLANK ) + +/** + * @brief A combination of bit masks for HD video sync types + * @see ::MBG_GPIO_VIDEO_SYNC_TYPE_MASKS + */ +#define MBG_GPIO_VIDEO_SYNC_HD_TYPES ( MSK_MBG_GPIO_VIDEO_SYNC_TYPE_OFF | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_HSYNC | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_VSYNC | \ + MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_FRAME | MSK_MBG_GPIO_VIDEO_SYNC_TYPE_HD_BLANK ) + + + +/** + * @brief Configuration of a GPIO as sync output module + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_VIDEO_SYNC_OUT + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t type; ///< sync type, see :: MBG_GPIO_SYNC_TYPES + uint32_t flags; ///< flags, currently always 0 + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + uint32_t reserved2; ///< reserved, currently always 0 + uint32_t reserved3; ///< reserved, currently always 0 + +} MBG_GPIO_VIDEO_SYNC_OUT_SETTINGS; + +#define _mbg_swab_mbg_gpio_video_sync_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->type ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ + _mbg_swab32( &(_p)->reserved3 ); \ +} while ( 0 ) + + + +/** + * @brief Supported options of a sync type GPIO output + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_VIDEO_SYNC_OUT + * @see ::MBG_GPIO_LIMITS + */ +typedef struct +{ + uint32_t supp_types; ///< supported types, see ::MBG_GPIO_VIDEO_SYNC_TYPE_MASKS + uint32_t supp_flags; ///< supported flags, currently always 0 + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + +} MBG_GPIO_VIDEO_SYNC_OUT_SUPP; + +#define _mbg_swab_mbg_gpio_video_sync_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_types ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ +} while ( 0 ) + - /// settings depending on the GPIO type, see ::MBG_GPIO_TYPES + +/** + * @brief Enumeration of studio clock base frequencies + * + * Used with ::MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS::base_freq + * + * @see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_MASKS + */ +enum MBG_GPIO_STUDIO_CLOCK_BASE_FREQS +{ + MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ, ///< 32 kHz base frequency + MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ, ///< 44.1 kHz base frequency + MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ, ///< 48 kHz base frequency + N_MBG_GPIO_STUDIO_CLOCK_BASE_FREQS ///< number of defined base frequencies +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQS + * + * Used with ::MBG_GPIO_STUDIO_CLOCK_OUT_SUPP::supp_base_freqs + * + * @see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQS + */ +enum MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_MASKS +{ + MSK_MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ = ( 1UL << MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ ), ///< See ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_32KHZ + MSK_MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ = ( 1UL << MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ ), ///< See ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_44_1KHZ + MSK_MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ = ( 1UL << MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ ) ///< See ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_48KHZ +}; + + + +/** + * @brief Initializers for an array of base frequencies of studio clock output name strings + * + * @see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQS + * @see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_MASKS + */ +#define MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_STRS \ +{ \ + "32 kHz", \ + "44.1 kHz", \ + "48 kHz" \ +} + + + +/** + * @brief Enumeration of studio clock scales + * + * Used with ::MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS::scale + * Multiply scale with base frequency + * + * @see ::MBG_GPIO_STUDIO_CLOCK_SCALE_MASKS + */ +enum MBG_GPIO_STUDIO_CLOCK_SCALES +{ + MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32, + MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16, + MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8, + MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4, + MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2, + MBG_GPIO_STUDIO_CLOCK_SCALE_1, + MBG_GPIO_STUDIO_CLOCK_SCALE_2, + MBG_GPIO_STUDIO_CLOCK_SCALE_4, + MBG_GPIO_STUDIO_CLOCK_SCALE_8, + MBG_GPIO_STUDIO_CLOCK_SCALE_16, + MBG_GPIO_STUDIO_CLOCK_SCALE_32, + MBG_GPIO_STUDIO_CLOCK_SCALE_64, + MBG_GPIO_STUDIO_CLOCK_SCALE_128, + MBG_GPIO_STUDIO_CLOCK_SCALE_256, + MBG_GPIO_STUDIO_CLOCK_SCALE_512, + N_MBG_GPIO_STUDIO_CLOCK_SCALES ///< number of defined scales +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_STUDIO_CLOCK_SCALES + * + * Used with ::MBG_GPIO_STUDIO_CLOCK_OUT_SUPP::supp_scales[N_MBG_GPIO_STUDIO_CLOCK_BASE_FREQS] + * + * @see ::MBG_GPIO_STUDIO_CLOCK_SCALES + */ +enum MBG_GPIO_STUDIO_CLOCK_SCALE_MASKS +{ + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_32 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_16 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_8 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_4 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1_DIV_2 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_1 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_1 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_1 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_2 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_2 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_2 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_4 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_4 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_4 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_8 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_8 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_8 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_16 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_16 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_16 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_32 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_32 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_32 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_64 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_64 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_64 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_128 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_128 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_128 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_256 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_256 ), ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_256 + MSK_MBG_GPIO_STUDIO_CLOCK_SCALE_512 = ( 1U << MBG_GPIO_STUDIO_CLOCK_SCALE_512 ) ///< See ::MBG_GPIO_STUDIO_CLOCK_SCALE_512 +}; + + + +/** + * @brief Initializers for an array of scales of studio clock output name strings + * + * @see ::MBG_GPIO_STUDIO_CLOCK_SCALES + * @see ::MBG_GPIO_STUDIO_CLOCK_SCALE_MASKS + */ +#define MBG_GPIO_STUDIO_CLOCK_SCALE_STRS \ +{ \ + "1/32", \ + "1/16", \ + "1/8", \ + "1/4", \ + "1/2", \ + "1", \ + "2", \ + "4", \ + "8", \ + "16", \ + "32", \ + "64", \ + "128", \ + "256", \ + "512" \ +} + + + +/** + * @brief Enumeration of flags used with studio clock type GPIO outputs + */ +enum MBG_GPIO_STUDIO_CLOCK_FLAGS +{ + MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED, ///< if set, enables output + N_MBG_GPIO_STUDIO_CLOCK_FLAGS ///< number of known flags +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_STUDIO_CLOCK_FLAGS + * + * Used with ::MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS::flags + * + * @see ::MBG_GPIO_STUDIO_CLOCK_FLAGS + */ +enum MBG_GPIO_STUDIO_CLOCK_FLAG_MASKS +{ + MSK_MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED = ( 1UL << MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED ) ///< See ::MBG_GPIO_STUDIO_CLOCK_OUTPUT_ENABLED +}; + + + +/** + * @brief Configuration of a GPIO as studio clock output module + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_STUDIO_CLOCK_OUT + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t base_freq; ///< base frequency, see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQS + uint32_t scale; ///< scale, see ::MBG_GPIO_STUDIO_CLOCK_SCALES + uint32_t flags; ///< flags, see ::MBG_GPIO_STUDIO_CLOCK_FLAGS + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + +} MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS; + +#define _mbg_swab_mbg_gpio_studio_clock_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->base_freq ); \ + _mbg_swab32( &(_p)->scale ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ +} while ( 0 ) + + + +#define MAX_SUPP_BASE_FREQUENCIES 8 ///< max. supported base frequencies for studio clock outputs + +/** + * @brief Configuration of a GPIO as studio clock output module + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_STUDIO_CLOCK_OUT + * @see ::MBG_GPIO_LIMITS + */ +typedef struct +{ + uint8_t supp_base_freqs; ///< supported base frequencies, see ::MBG_GPIO_STUDIO_CLOCK_BASE_FREQ_MASKS + uint8_t reserved0; ///< reserved, currently always 0 + uint16_t reserved1; ///< reserved, currently always 0 + uint16_t supp_scales[MAX_SUPP_BASE_FREQUENCIES]; ///< supported scales for each base frequency, see ::MBG_GPIO_STUDIO_CLOCK_SCALE_MASKS + uint32_t supp_flags; ///< supported flags, see::MBG_GPIO_STUDIO_CLOCK_FLAG_MASKS + uint32_t reserved2; ///< reserved, currently always 0 + +} MBG_GPIO_STUDIO_CLOCK_OUT_SUPP; + +#define _mbg_swab_mbg_gpio_studio_clock_out_supp( _p ) \ +do \ +{ \ + uint8_t idx; \ + _mbg_swab8( &(_p)->supp_base_freqs ); \ + _mbg_swab8( &(_p)->reserved0 ); \ + _mbg_swab16( &(_p)->reserved1 ); \ + for( idx = 0; idx < MAX_SUPP_BASE_FREQUENCIES; idx++ ) \ + _mbg_swab16( &(_p)->supp_scales[idx] ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved2 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of types used with GPIO type digital audio outputs + * + * Used with ::MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS::type, and to + * define ::MBG_GPIO_DIGITAL_AUDIO_TYPE_MASKS + * + * @see ::MBG_GPIO_DIGITAL_AUDIO_TYPE_MASKS + * @see ::MBG_GPIO_DIGITAL_AUDIO_TYPE_STRS + */ +enum MBG_GPIO_DIGITAL_AUDIO_TYPES +{ + MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF, + MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS, ///< DARS + N_MBG_GPIO_DIGITAL_AUDIO_TYPES ///< number of known types +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_DIGITAL_AUDIO_TYPES + * + * Used with :: MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT_SUPP::supp_types + * + * @see ::MBG_GPIO_DIGITAL_AUDIO_TYPES + */ +enum MBG_GPIO_DIGITAL_AUDIO_TYPE_MASKS +{ + MSK_MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF = ( 1UL << MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF ), ///< See ::MBG_GPIO_DIGITAL_AUDIO_TYPE_OFF + MSK_MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS = ( 1UL << MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS ) ///< See ::MBG_GPIO_DIGITAL_AUDIO_TYPE_DARS +}; + + + +/** + * @brief Initializers for an array of video epoch strings + * + * @see ::MBG_GPIO_VIDEO_EPOCHS + */ +#define MBG_GPIO_DIGITAL_AUDIO_TYPE_STRS \ +{ \ + "OFF", \ + "DARS" \ +} + + + +/** + * @brief Enumeration of flags used with GPIO type digital audio outputs + */ +enum MBG_GPIO_DIGITAL_AUDIO_FLAGS +{ + MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG, ///< reserved + N_MBG_GPIO_DIGITAL_AUDIO_FLAGS ///< number of known flags +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_DIGITAL_AUDIO_FLAGS + * + * Used with ::MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS::flags + * + * @see ::MBG_GPIO_DIGITAL_AUDIO_FLAGS + */ +enum MBG_GPIO_DIGITAL_AUDIO_FLAG_MASKS +{ + MSK_MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG = ( 1UL << MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG ) ///< See ::MBG_GPIO_DIGITAL_AUDIO_RESERVED_FLAG +}; + + + +/** + * @brief Configuration of a GPIO digital audio output + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t type; ///< digital audio type, see ::MBG_GPIO_DIGITAL_AUDIO_TYPES + uint32_t flags; ///< reserved, currently always 0 + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + uint32_t reserved2; ///< reserved, currently always 0 + +} MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS; + + + +#define _mbg_swab_mbg_gpio_digital_audio_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->type ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ +} while ( 0 ) + + + +/** + * @brief Supported options for digital audio output + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT + * @see ::MBG_GPIO_LIMITS + */ +typedef struct +{ + uint32_t supp_types; ///< supported digital audio types, see ::MBG_GPIO_DIGITAL_AUDIO_TYPE_MASKS + uint32_t supp_flags; ///< reserved, currently always 0 + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + uint32_t reserved2; ///< reserved, currently always 0 + +} MBG_GPIO_DIGITAL_AUDIO_OUT_SUPP; + + + +#define _mbg_swab_mbg_gpio_digital_audio_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_types ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of physical video input signal sources + * + * Video can be received over a single or differential signals + * + * @see MBG_GPIO_VIDEO_IN_SETTINGS + */ +enum MBG_GPIO_VIDEO_IN_SIGNAL_SRCS +{ + MBG_GPIO_VIDEO_IN_SIGNAL_SRC_SES, ///< single-ended signal video input + MBG_GPIO_VIDEO_IN_SIGNAL_SRC_DIFFERENTIAL, ///< differential signal line video input + N_MBG_GPIO_VIDEO_IN_SIGNAL_SRCS ///< number of possible signal sources +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_VIDEO_IN_SIGNAL_SRCS + * + * Used with ::MBG_GPIO_VIDEO_IN_SETTINGS::tc_mode + * + */ +enum MBG_GPIO_VIDEO_IN_SIGNAL_SRC_MASKS +{ + MSK_MBG_GPIO_VIDEO_IN_SIGNAL_SRC_SES = ( 1UL << MBG_GPIO_VIDEO_IN_SIGNAL_SRC_SES ), ///< See ::MBG_GPIO_VIDEO_IN_SIGNAL_SRC_SES + MSK_MBG_GPIO_VIDEO_IN_SIGNAL_SRC_DIFFERENTIAL = ( 1UL << MBG_GPIO_VIDEO_IN_SIGNAL_SRC_DIFFERENTIAL ) ///< See ::MBG_GPIO_VIDEO_IN_SIGNAL_SRC_DIFFERENTIAL +}; + + + + +/** + * @brief Initializers for an array of video signal input source strings + * + * @see ::MBG_GPIO_VIDEO_IN_SIGNAL_SRCS + * @see ::MBG_GPIO_VIDEO_IN_SIGNAL_SRC_MASKS + */ +#define MBG_GPIO_VIDEO_IN_SIGNAL_SRC_STRS \ +{ \ + "Single-ended signal input", \ + "Differential signal input" \ +} + + + +/** + * @brief Configuration of a GPIO as video input module + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS + * + * @see ::MBG_GPIO_TYPE_VIDEO_IN + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t format; ///< video format, see ::MBG_GPIO_VIDEO_FORMATS + + uint8_t epoch; ///< epoch, see ::MBG_GPIO_VIDEO_EPOCHS + uint8_t signal_src; ///< video input signal source, see ::MBG_GPIO_VIDEO_IN_SIGNAL_SRCS + uint8_t tc_mode; ///< time code mode, see ::MBG_GPIO_VIDEO_TC_MODES + uint8_t tc_line; ///< time code line location, valid lines: 6-22 + + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + uint32_t reserved2; ///< reserved, currently always 0 +} MBG_GPIO_VIDEO_IN_SETTINGS; + + + +#define _mbg_swab_mbg_gpio_video_in_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->format ); \ + _mbg_swab8( &(_p)->epoch ); \ + _mbg_swab8( &(_p)->signal_src ); \ + _mbg_swab8( &(_p)->tc_mode ); \ + _mbg_swab8( &(_p)->tc_line ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t supp_formats; ///< supported video formats, see ::MBG_GPIO_VIDEO_FORMAT_MASKS + uint32_t supp_epochs; ///< supported epochs, see ::MBG_GPIO_VIDEO_EPOCH_MASKS + + uint32_t supp_signal_srcs; ///< video input signal sources, see ::MBG_GPIO_VIDEO_IN_SIGNAL_SRC_MASKS + uint32_t supp_tc_modes; ///< time code mode, see ::MBG_GPIO_VIDEO_TC_MODE_MASKS + + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + uint32_t reserved2; ///< reserved, currently always 0 + +} MBG_GPIO_VIDEO_IN_SUPP; + + + +#define _mbg_swab_mbg_gpio_video_in_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_formats ); \ + _mbg_swab32( &(_p)->supp_epochs ); \ + _mbg_swab32( &(_p)->supp_signal_srcs ); \ + _mbg_swab32( &(_p)->supp_tc_modes ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ + _mbg_swab32( &(_p)->reserved3 ); \ +} while ( 0 ) + + +/** + * @brief Enumeration of types used with GPIO type LTC outputs + * + * Used with ::MBG_GPIO_LTC_OUT_SETTINGS::type, and to + * define ::MBG_GPIO_LTC_OUT_TYPE_MASKS + * + * @see ::MBG_GPIO_LTC_OUT_TYPE_MASKS + * @see ::MBG_GPIO_LTC_OUT_TYPE_STRS + */ +enum MBG_GPIO_LTC_OUT_TYPES +{ + MBG_GPIO_LTC_OUT_OFF, + MBG_GPIO_LTC_OUT_TYPE_24FPS_23_976Hz, + MBG_GPIO_LTC_OUT_TYPE_24FPS, + MBG_GPIO_LTC_OUT_TYPE_25FPS, + MBG_GPIO_LTC_OUT_TYPE_30FPS, + MBG_GPIO_LTC_OUT_TYPE_30FPS_DROP_FRAME, + N_MBG_GPIO_LTC_OUT_TYPES ///< number of known types +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_LTC_OUT_TYPES + * + * Used with :: MBG_GPIO_TYPE_LTC_OUT_SUPP::supp_types + * + * @see ::MBG_GPIO_LTC_OUT_TYPES + */ +enum MBG_GPIO_LTC_OUT_TYPE_MASKS +{ + MSK_MBG_GPIO_LTC_OUT_OFF = ( 1UL << MBG_GPIO_LTC_OUT_OFF ), ///< See ::MBG_GPIO_LTC_OUT_OFF + MSK_MBG_GPIO_LTC_OUT_TYPE_24FPS_23_976Hz = ( 1UL << MBG_GPIO_LTC_OUT_TYPE_24FPS_23_976Hz ), ///< See ::MBG_GPIO_LTC_OUT_TYPE_24FPS_23_976Hz + MSK_MBG_GPIO_LTC_OUT_TYPE_24FPS = ( 1UL << MBG_GPIO_LTC_OUT_TYPE_24FPS ), ///< See ::MBG_GPIO_LTC_OUT_TYPE_24FPS + MSK_MBG_GPIO_LTC_OUT_TYPE_25FPS = ( 1UL << MBG_GPIO_LTC_OUT_TYPE_25FPS ), ///< See ::MBG_GPIO_LTC_OUT_TYPE_25FPS + MSK_MBG_GPIO_LTC_OUT_TYPE_30FPS = ( 1UL << MBG_GPIO_LTC_OUT_TYPE_30FPS ), ///< See ::MBG_GPIO_LTC_OUT_TYPE_30FPS + MSK_MBG_GPIO_LTC_OUT_TYPE_30FPS_DROP_FRAME = ( 1UL << MBG_GPIO_LTC_OUT_TYPE_30FPS_DROP_FRAME ) ///< See ::MBG_GPIO_LTC_OUT_TYPE_30FPS_DROP_FRAME +}; + +/** + * @brief Initializers for an array of ltc out strings + * + * @see ::MBG_GPIO_LTC_OUT_TYPES + */ +#define MBG_GPIO_LTC_OUT_TYPE_STRS \ +{ \ + "OFF", \ + "LTC 24FPS / 23.976Hz", \ + "LTC 24FPS", \ + "LTC 25FPS", \ + "LTC 30FPS", \ + "LTC 30FPS Drop Frame" \ +} + +/** + * @brief Enumeration of flags used with GPIO type LTC outputs + */ +enum MBG_GPIO_LTC_OUT_FLAGS +{ + MBG_GPIO_LTC_OUT_RESERVED_FLAG, ///< reserved + N_MBG_GPIO_LTC_OUT_FLAGS ///< number of known flags +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_LTC_OUT_FLAGS + * + * Used with ::MBG_GPIO_LTC_OUT_SETTINGS::flags + * + * @see ::MBG_GPIO_LTC_OUT_FLAGS + */ +enum MBG_GPIO_LTC_OUT_FLAG_MASKS +{ + MSK_MBG_GPIO_LTC_OUT_RESERVED_FLAG = ( 1UL << MBG_GPIO_LTC_OUT_RESERVED_FLAG ) ///< See ::MBG_GPIO_LTC_OUT_RESERVED_FLAG +}; + + + +/** + * @brief Configuration of a GPIO LTC output + * + * Used as sub-structure of ::MBG_GPIO_SETTINGS. + * + * @see ::MBG_GPIO_TYPE_LTC_OUT + * @see ::MBG_GPIO_SETTINGS + */ +typedef struct +{ + uint32_t type; ///< LTC type, see ::MBG_GPIO_LTC_OUT_TYPES + uint32_t flags; ///< reserved, currently always 0 + uint32_t reserved0; ///< reserved, currently always 0 + uint32_t reserved1; ///< reserved, currently always 0 + uint32_t reserved2; ///< reserved, currently always 0 + +} MBG_GPIO_LTC_OUT_SETTINGS; + + + +#define _mbg_swab_mbg_gpio_ltc_out_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->type ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved0 ); \ + _mbg_swab32( &(_p)->reserved1 ); \ + _mbg_swab32( &(_p)->reserved2 ); \ +} while ( 0 ) + + + +/** + * @brief Supported options for LTC output + * + * Used as sub-structure of ::MBG_GPIO_LIMITS. + * + * @see ::MBG_GPIO_TYPE_LTC_OUT + * @see ::MBG_GPIO_LIMITS + */ +typedef struct +{ + uint32_t supp_types; ///< Supported LTC types, see ::MBG_GPIO_LTC_OUT_TYPE_MASKS. + uint32_t supp_flags; ///< Reserved, currently always 0. + uint32_t reserved_0; ///< Reserved, currently always 0. + uint32_t reserved_1; ///< Reserved, currently always 0. + uint32_t reserved_2; ///< Reserved, currently always 0. + +} MBG_GPIO_LTC_OUT_SUPP; + + +#define _mbg_swab_mbg_gpio_ltc_out_supp( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_types ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of general flags used with a GPIO + * + * @see ::MBG_GPIO_FLAG_MASKS + */ +enum MBG_GPIO_FLAGS +{ + MBG_GPIO_DEPENDS_ON_ASS_IO_IDX, ///< indicates that this output depends on GPIO with ::MBG_GPIO_SETTINGS::ass_io_idx and may not be configured independently + MBG_GPIO_PORT_INVISIBLE, ///< gpio is used internally and should not be displayed by config apps + N_MBG_GPIO_FLAGS ///< number of known flags +}; + + + +/** + * @brief Bit masks associated with ::MBG_GPIO_FLAGS. + * + * Used with ::MBG_GPIO_LIMITS::supp_flags and ::MBG_GPIO_SETTINGS::flags. + * + * @see ::MBG_GPIO_FLAGS + */ +enum MBG_GPIO_FLAG_MASKS +{ + MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX = ( 1UL << MBG_GPIO_DEPENDS_ON_ASS_IO_IDX ), ///< See ::MBG_GPIO_DEPENDS_ON_ASS_IO_IDX + MSK_MBG_GPIO_PORT_INVISIBLE = ( 1UL << MBG_GPIO_PORT_INVISIBLE ) ///< See ::MBG_GPIO_PORT_INVISIBLE +}; + + + +/** + * @brief A generic structure used to hold the settings of a GPIO port. + */ +typedef struct +{ + uint32_t type; ///< GPIO type, see ::MBG_GPIO_TYPES. + + uint16_t reserved_1; ///< Reserved, currently always 0. + uint8_t reserved_2; ///< Reserved, currently always 0. + uint8_t ass_io_idx; ///< Associated GPIO index, only valid if ::MSK_MBG_GPIO_DEPENDS_ON_ASS_IO_IDX is set in flags field. + + uint32_t flags; ///< Flags, see ::MBG_GPIO_FLAG_MASKS. + + /// @brief Settings depending on the GPIO @a #type, see ::MBG_GPIO_TYPES. union { - MBG_GPIO_FREQ_IN_SETTINGS freq_in; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_IN - MBG_GPIO_FREQ_OUT_SETTINGS freq_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_OUT - MBG_GPIO_FIXED_FREQ_OUT_SETTINGS ff_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FIXED_FREQ_OUT - MBG_GPIO_BITS_IN_SETTINGS bits_in; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_IN - MBG_GPIO_BITS_OUT_SETTINGS bits_out; ///< if ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_OUT + uint32_t b[6]; ///< Just to indicate the size of this union. + MBG_GPIO_FREQ_IN_SETTINGS freq_in; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_IN + MBG_GPIO_FREQ_OUT_SETTINGS freq_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_OUT + MBG_GPIO_FIXED_FREQ_OUT_SETTINGS ff_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FIXED_FREQ_OUT + MBG_GPIO_BITS_IN_SETTINGS bits_in; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_IN + MBG_GPIO_BITS_OUT_SETTINGS bits_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_OUT + MBG_GPIO_VIDEO_OUT_SETTINGS video_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_OUT + MBG_GPIO_VIDEO_SYNC_OUT_SETTINGS video_sync_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_SYNC_OUT + MBG_GPIO_STUDIO_CLOCK_OUT_SETTINGS studio_clk_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_STUDIO_CLOCK_OUT + MBG_GPIO_DIGITAL_AUDIO_OUT_SETTINGS digital_audio_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT + MBG_GPIO_VIDEO_IN_SETTINGS video_in; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_IN + MBG_GPIO_LTC_OUT_SETTINGS ltc_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_LTC_OUT } u; } MBG_GPIO_SETTINGS; - - -/** - * @brief A GPIO port's current settings, plus port index +#define _mbg_swab_mbg_gpio_settings( _p, _recv ) \ +do \ +{ \ + uint32_t t = (_p)->type; \ + if ( (_recv) ) \ + _mbg_swab32( &t ); \ + _mbg_swab32( &(_p)->type ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab8( &(_p)->reserved_2 ); \ + _mbg_swab8( &(_p)->ass_io_idx ); \ + _mbg_swab32( &(_p)->flags ); \ + switch( t ) \ + { \ + case MBG_GPIO_TYPE_FREQ_IN : _mbg_swab_mbg_gpio_freq_in_settings( &(_p)->u.freq_in ); break; \ + case MBG_GPIO_TYPE_FREQ_OUT : _mbg_swab_mbg_gpio_freq_out_settings( &(_p)->u.freq_out ); break; \ + case MBG_GPIO_TYPE_FIXED_FREQ_OUT : _mbg_swab_mbg_gpio_fixed_freq_out_settings( &(_p)->u.ff_out ); break; \ + case MBG_GPIO_TYPE_BITS_IN : _mbg_swab_mbg_gpio_bits_in_settings( &(_p)->u.bits_in, (_recv) ); break; \ + case MBG_GPIO_TYPE_BITS_OUT : _mbg_swab_mbg_gpio_bits_out_settings( &(_p)->u.bits_out ); break; \ + case MBG_GPIO_TYPE_VIDEO_OUT : _mbg_swab_mbg_gpio_video_out_settings( &(_p)->u.video_out ); break; \ + case MBG_GPIO_TYPE_VIDEO_SYNC_OUT : _mbg_swab_mbg_gpio_video_sync_out_settings( &(_p)->u.video_sync_out ); break; \ + case MBG_GPIO_TYPE_STUDIO_CLOCK_OUT : _mbg_swab_mbg_gpio_studio_clock_out_settings( &(_p)->u.studio_clk_out ); break; \ + case MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT : _mbg_swab_mbg_gpio_digital_audio_out_settings( &(_p)->u.digital_audio_out ); break; \ + case MBG_GPIO_TYPE_VIDEO_IN : _mbg_swab_mbg_gpio_video_in_settings( &(_p)->u.video_in ); break; \ + case MBG_GPIO_TYPE_LTC_OUT : _mbg_swab_mbg_gpio_ltc_out_settings( &(_p)->u.ltc_out ); break; \ + default : break; \ + } \ +} while ( 0 ) + + + +/** + * @brief The current settings of a GPIO port, plus port index. */ typedef struct { - uint32_t idx; ///< port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1 - MBG_GPIO_SETTINGS settings; ///< current settings + MBG_MSG_IDX_32 idx; ///< GPIO port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1. + MBG_GPIO_SETTINGS settings; ///< Current settings } MBG_GPIO_SETTINGS_IDX; +#define _mbg_swab_mbg_gpio_settings_idx( _p, _recv ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_gpio_settings( &(_p)->settings, (_recv ) ); \ +} while ( 0 ) + /** - * @brief A generic structure used to specify a GPIO port's limits + * @brief A generic structure used to specify the limits of a GPIO port. */ typedef struct { uint32_t type; ///< GPIO type, see ::MBG_GPIO_TYPES uint32_t reserved; ///< reserved, currently always 0 - uint32_t supp_flags; ///< supported flags //##++++++++++++ which? + uint32_t supp_flags; ///< supported flags, see ::MBG_GPIO_FLAG_MASKS - /// limits depending on the GPIO type, see ::MBG_GPIO_TYPES + /// Limits depending on the GPIO type, see ::MBG_GPIO_TYPES. union { - MBG_GPIO_FREQ_IN_SUPP freq_in; ///< if type is ::MBG_GPIO_TYPE_FREQ_IN - MBG_GPIO_FREQ_OUT_SUPP freq_out; ///< if type is ::MBG_GPIO_TYPE_FREQ_OUT - MBG_GPIO_FIXED_FREQ_OUT_SUPP ff_out; ///< if type is ::MBG_GPIO_TYPE_FIXED_FREQ_OUT - MBG_GPIO_BITS_IN_SUPP bits_in; ///< if type is ::MBG_GPIO_TYPE_BITS_IN - MBG_GPIO_BITS_OUT_SUPP bits_out; ///< if type is ::MBG_GPIO_TYPE_BITS_OUT + uint32_t b[7]; ///< Just to indicate the size of this union. + MBG_GPIO_FREQ_IN_SUPP freq_in; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_IN + MBG_GPIO_FREQ_OUT_SUPP freq_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FREQ_OUT + MBG_GPIO_FIXED_FREQ_OUT_SUPP ff_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_FIXED_FREQ_OUT + MBG_GPIO_BITS_IN_SUPP bits_in; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_IN + MBG_GPIO_BITS_OUT_SUPP bits_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_BITS_OUT + MBG_GPIO_VIDEO_OUT_SUPP video_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_OUT + MBG_GPIO_VIDEO_SYNC_OUT_SUPP video_sync_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_SYNC_OUT + MBG_GPIO_STUDIO_CLOCK_OUT_SUPP studio_clk_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_STUDIO_CLOCK_OUT + MBG_GPIO_DIGITAL_AUDIO_OUT_SUPP digital_audio_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT + MBG_GPIO_VIDEO_IN_SUPP video_in; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_VIDEO_IN + MBG_GPIO_LTC_OUT_SUPP ltc_out; ///< If ::MBG_GPIO_SETTINGS::type is ::MBG_GPIO_TYPE_LTC_OUT } u; } MBG_GPIO_LIMITS; - - -/** - * @brief A GPIO port's current settings and limits +#define _mbg_swab_mbg_gpio_limits( _p, _recv ) \ +do \ +{ \ + uint32_t t = (_p)->type; \ + if ( (_recv) ) \ + _mbg_swab32( &t ); \ + _mbg_swab32( &(_p)->type ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + switch( t ) \ + { \ + case MBG_GPIO_TYPE_FREQ_IN : _mbg_swab_mbg_gpio_freq_in_supp( &(_p)->u.freq_in ); break; \ + case MBG_GPIO_TYPE_FREQ_OUT : _mbg_swab_mbg_gpio_freq_out_supp( &(_p)->u.freq_out ); break; \ + case MBG_GPIO_TYPE_FIXED_FREQ_OUT : _mbg_swab_mbg_gpio_fixed_freq_out_supp( &(_p)->u.ff_out ); break; \ + case MBG_GPIO_TYPE_BITS_IN : _mbg_swab_mbg_gpio_bits_in_supp( &(_p)->u.bits_in ); break; \ + case MBG_GPIO_TYPE_BITS_OUT : _mbg_swab_mbg_gpio_bits_out_supp( &(_p)->u.bits_out ); break; \ + case MBG_GPIO_TYPE_VIDEO_OUT : _mbg_swab_mbg_gpio_video_out_supp( &(_p)->u.video_out ); break; \ + case MBG_GPIO_TYPE_VIDEO_SYNC_OUT : _mbg_swab_mbg_gpio_video_sync_out_supp( &(_p)->u.video_sync_out ); break; \ + case MBG_GPIO_TYPE_STUDIO_CLOCK_OUT : _mbg_swab_mbg_gpio_studio_clock_out_supp( &(_p)->u.studio_clk_out ); break; \ + case MBG_GPIO_TYPE_DIGITAL_AUDIO_OUT : _mbg_swab_mbg_gpio_digital_audio_out_supp( &(_p)->u.digital_audio_out ); break; \ + case MBG_GPIO_TYPE_VIDEO_IN : _mbg_swab_mbg_gpio_video_in_supp( &(_p)->u.video_in ); break; \ + case MBG_GPIO_TYPE_LTC_OUT : _mbg_swab_mbg_gpio_ltc_out_supp( &(_p)->u.ltc_out ); break; \ + default : break; \ + } \ +} while ( 0 ) + + + +/** + * @brief The current settings and limits of a GPIO port. */ typedef struct { - MBG_GPIO_SETTINGS settings; ///< current settings - MBG_GPIO_LIMITS limits; ///< limits of this GPIO port + MBG_GPIO_SETTINGS settings; ///< Current settings. + MBG_GPIO_LIMITS limits; ///< Limits of this GPIO port. } MBG_GPIO_INFO; +#define _mbg_swab_mbg_gpio_info( _p, _recv ) \ +do \ +{ \ + _mbg_swab_mbg_gpio_settings( &(_p)->settings, (_recv) ); \ + _mbg_swab_mbg_gpio_limits( &(_p)->limits, (_recv) ); \ +} while ( 0 ) + /** - * @brief A GPIO port's current settings and limits, plus port index + * @brief The current settings and limits of a GPIO port, plus port index. */ typedef struct { - uint32_t idx; ///< port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1 - MBG_GPIO_INFO info; ///< limits and current settings of this GPIO port + MBG_MSG_IDX_32 idx; ///< Port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1. + MBG_GPIO_INFO info; ///< Limits and current settings of this GPIO port. } MBG_GPIO_INFO_IDX; +#define _mbg_swab_mbg_gpio_info_idx( _p, _recv ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_gpio_info( &(_p)->info, (_recv) ); \ +} while ( 0 ) + /** @@ -6359,14 +9995,24 @@ typedef struct */ typedef struct { - uint8_t port_state; ///< see ::MBG_GPIO_PORT_STATES - uint8_t reserved_0; ///< reserved, currently unused and always 0 - uint16_t reserved_1; ///< reserved, currently unused and always 0 - uint32_t reserved_2; ///< reserved, currently unused and always 0 - uint32_t reserved_3; ///< reserved, currently unused and always 0 + uint8_t port_state; ///< See ::MBG_GPIO_PORT_STATES. + uint8_t reserved_0; ///< Reserved, currently unused and always 0. + uint16_t reserved_1; ///< Reserved, currently unused and always 0. + uint32_t reserved_2; ///< Reserved, currently unused and always 0. + uint32_t reserved_3; ///< Reserved, currently unused and always 0. } MBG_GPIO_STATUS; +#define _mbg_swab_mbg_gpio_status( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->port_state ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + /** @@ -6374,11 +10020,18 @@ typedef struct */ typedef struct { - uint16_t idx; ///< port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1 - MBG_GPIO_STATUS status; ///< status information + MBG_MSG_IDX idx; ///< GPIO port index, 0..::MBG_GPIO_CFG_LIMITS::num_io-1. + MBG_GPIO_STATUS status; ///< Status information. } MBG_GPIO_STATUS_IDX; +#define _mbg_swab_mbg_gpio_status_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_mbg_gpio_status( &(_p)->status ); \ +} while ( 0 ) + /** @@ -6450,12 +10103,12 @@ enum HAVEQUICK_FORMATS */ enum HAVEQUICK_FORMAT_MASKS { - HQ_MSK_STANAG4246_1 = ( 1UL << HQ_FMT_STANAG4246_1 ), ///< see ::HQ_FMT_STANAG4246_1 - HQ_MSK_STANAG4246_2 = ( 1UL << HQ_FMT_STANAG4246_2 ), ///< see ::HQ_FMT_STANAG4246_2 - HQ_MSK_STANAG4246_PTTI = ( 1UL << HQ_FMT_STANAG4246_PTTI ), ///< see ::HQ_FMT_STANAG4246_PTTI - HQ_MSK_STANAG4372_SATURN_1 = ( 1UL << HQ_FMT_STANAG4372_SATURN_1 ), ///< see ::HQ_FMT_STANAG4372_SATURN_1 - HQ_MSK_STANAG4372_SATURN_2 = ( 1UL << HQ_FMT_STANAG4372_SATURN_2 ), ///< see ::HQ_FMT_STANAG4372_SATURN_2 - HQ_MSK_STANAG4430_EXTD = ( 1UL << HQ_FMT_STANAG4430_EXTD ) ///< see ::HQ_FMT_STANAG4430_EXTD + HQ_MSK_STANAG4246_1 = ( 1UL << HQ_FMT_STANAG4246_1 ), ///< See ::HQ_FMT_STANAG4246_1 + HQ_MSK_STANAG4246_2 = ( 1UL << HQ_FMT_STANAG4246_2 ), ///< See ::HQ_FMT_STANAG4246_2 + HQ_MSK_STANAG4246_PTTI = ( 1UL << HQ_FMT_STANAG4246_PTTI ), ///< See ::HQ_FMT_STANAG4246_PTTI + HQ_MSK_STANAG4372_SATURN_1 = ( 1UL << HQ_FMT_STANAG4372_SATURN_1 ), ///< See ::HQ_FMT_STANAG4372_SATURN_1 + HQ_MSK_STANAG4372_SATURN_2 = ( 1UL << HQ_FMT_STANAG4372_SATURN_2 ), ///< See ::HQ_FMT_STANAG4372_SATURN_2 + HQ_MSK_STANAG4430_EXTD = ( 1UL << HQ_FMT_STANAG4430_EXTD ) ///< See ::HQ_FMT_STANAG4430_EXTD }; /* @@ -6506,8 +10159,8 @@ enum HAVEQUICK_FORMAT_MASKS */ typedef struct { - uint16_t format; ///< see ::HAVEQUICK_FORMATS - uint16_t flags; ///< see ::HAVEQUICK_FLAG_MASKS + uint16_t format; ///< See ::HAVEQUICK_FORMATS + uint16_t flags; ///< See ::HAVEQUICK_FLAG_MASKS int32_t offset; ///< Tx: unused, Rx: offset of incoming time in [s] uint32_t reserved_0; ///< reserved, currently always 0 uint32_t reserved_1; ///< reserved, currently always 0 @@ -6515,13 +10168,14 @@ typedef struct } HAVEQUICK_SETTINGS; #define _mbg_swab_havequick_settings( _p ) \ +do \ { \ _mbg_swab16( &(_p)->format ); \ _mbg_swab16( &(_p)->flags ); \ _mbg_swab32( &(_p)->offset ); \ _mbg_swab32( &(_p)->reserved_0 ); \ _mbg_swab32( &(_p)->reserved_1 ); \ -} +} while ( 0 ) /** * @brief Current settings and capabilities of a HaveQuick input or output @@ -6529,19 +10183,20 @@ typedef struct typedef struct { HAVEQUICK_SETTINGS settings; ///< current settings - uint32_t supp_formats; ///< see ::HAVEQUICK_FORMAT_MASKS + uint32_t supp_formats; ///< See ::HAVEQUICK_FORMAT_MASKS uint16_t supp_flags; ///< mask of flags supported in settings, see ::HAVEQUICK_FLAG_MASKS uint16_t reserved; ///< reserved, currently always 0 } HAVEQUICK_INFO; #define _mbg_swab_havequick_info( _p ) \ +do \ { \ _mbg_swab_havequick_settings( &(_p)->settings ); \ _mbg_swab32( &(_p)->supp_formats ); \ _mbg_swab16( &(_p)->supp_flags ); \ _mbg_swab16( &(_p)->reserved ); \ -} +} while ( 0 ) /** @@ -6567,9 +10222,9 @@ enum HAVEQUICK_FLAG_BITS */ enum HAVEQUICK_FLAG_MASKS { - HQ_MSK_TX_GEN_LOCAL_TIME = ( 1UL << HQ_FLAG_TX_GEN_LOCAL_TIME ), ///< see ::HQ_FLAG_TX_GEN_LOCAL_TIME - HQ_MSK_SIGNAL_INVERTED = ( 1UL << HQ_FLAG_SIGNAL_INVERTED ), ///< see ::HQ_FLAG_SIGNAL_INVERTED - HQ_MSK_USE_EXT_PPS = ( 1UL << HQ_FLAG_USE_EXT_PPS ) ///< see ::HQ_FLAG_USE_EXT_PPS + HQ_MSK_TX_GEN_LOCAL_TIME = ( 1UL << HQ_FLAG_TX_GEN_LOCAL_TIME ), ///< See ::HQ_FLAG_TX_GEN_LOCAL_TIME + HQ_MSK_SIGNAL_INVERTED = ( 1UL << HQ_FLAG_SIGNAL_INVERTED ), ///< See ::HQ_FLAG_SIGNAL_INVERTED + HQ_MSK_USE_EXT_PPS = ( 1UL << HQ_FLAG_USE_EXT_PPS ) ///< See ::HQ_FLAG_USE_EXT_PPS }; /** @} defgroup group_havequick */ @@ -6594,17 +10249,18 @@ typedef struct } MBG_NUM_EVT_LOG_ENTRIES; #define _mbg_swab_mbg_num_evt_log_entries( _p ) \ +do \ { \ _mbg_swab32( &(_p)->used ); \ _mbg_swab32( &(_p)->max ); \ -} +} while ( 0 ) typedef uint16_t MBG_EVT_CODE; -#define _mbg_swab_evt_code( _p ) _mbg_swab16( _p ); +#define _mbg_swab_evt_code( _p ) _mbg_swab16( _p ) typedef uint16_t MBG_EVT_INFO; -#define _mbg_swab_evt_info( _p ) _mbg_swab16( _p ); +#define _mbg_swab_evt_info( _p ) _mbg_swab16( _p ) /** * @brief An event log entry @@ -6618,11 +10274,12 @@ typedef struct } MBG_EVT_LOG_ENTRY; #define _mbg_swab_mbg_evt_log_entry( _p ) \ +do \ { \ _mbg_swab32( &(_p)->time ); \ _mbg_swab_evt_code( &(_p)->code ); \ _mbg_swab_evt_info( &(_p)->info ); \ -} +} while ( 0 ) // ::MBG_EVT_LOG_ENTRY::code is a combination of some bits used for the ID, @@ -6659,44 +10316,103 @@ typedef struct */ enum MBG_EVT_IDS { - MBG_EVT_ID_NONE, ///< no event (empty entry) - MBG_EVT_ID_POW_UP_RES, ///< power up reset - MBG_EVT_ID_WDOG_RES, ///< watchdog reset - MBG_EVT_ID_COLD_BOOT, ///< entering cold boot mode - MBG_EVT_ID_WARM_BOOT, ///< entering warm boot mode - MBG_EVT_ID_NORMAL_OP, ///< entering normal operation - MBG_EVT_ID_ANT_DISCONN, ///< antenna disconnect detected - MBG_EVT_ID_ANT_SHORT, ///< antenna short circuit detected - MBG_EVT_ID_ANT_OK, ///< antenna OK after failure - MBG_EVT_ID_LOW_SATS, ///< no satellites can be received though antenna not failing + MBG_EVT_ID_NONE, ///< no event (empty entry) + MBG_EVT_ID_POW_UP_RES, ///< power up reset + MBG_EVT_ID_WDOG_RES, ///< watchdog reset + MBG_EVT_ID_COLD_BOOT, ///< entering cold boot mode + MBG_EVT_ID_WARM_BOOT, ///< entering warm boot mode + MBG_EVT_ID_NORMAL_OP, ///< entering normal operation + MBG_EVT_ID_ANT_DISCONN, ///< antenna disconnect detected + MBG_EVT_ID_ANT_SHORT, ///< antenna short circuit detected + MBG_EVT_ID_ANT_OK, ///< antenna OK after failure + MBG_EVT_ID_LOW_SATS, ///< no satellites can be received though antenna not failing + MBG_EVT_ID_FW_INSTALLED, ///< Firmware has successfully been installed + MBG_EVT_ID_PTP_PORT_STATE_UNINITIALIZED, ///< PTP state changed to UNINITIALIZED + MBG_EVT_ID_PTP_PORT_STATE_INITIALIZING, ///< PTP state changed to INITIALIZING + MBG_EVT_ID_PTP_PORT_STATE_FAULTY, ///< PTP state changed to FAULTY + MBG_EVT_ID_PTP_PORT_STATE_DISABLED, ///< PTP state changed to DISABLED + MBG_EVT_ID_PTP_PORT_STATE_LISTENING, ///< PTP state changed to LISTENING + MBG_EVT_ID_PTP_PORT_STATE_PRE_MASTER, ///< PTP state changed to PRE_MASTER + MBG_EVT_ID_PTP_PORT_STATE_MASTER, ///< PTP state changed to MASTER + MBG_EVT_ID_PTP_PORT_STATE_PASSIVE, ///< PTP state changed to PASSIVE + MBG_EVT_ID_PTP_PORT_STATE_UNCALIBRATED, ///< PTP state changed to UNCALIBRATED + MBG_EVT_ID_PTP_PORT_STATE_SLAVE, ///< PTP state changed to SLAVE + MBG_EVT_ID_FW_ACTIVATED, ///< Firmware has been activated + MBG_EVT_ID_FW_DELETED, ///< Firmware has been deleted + MBG_EVT_ID_FW_ROLLBACK, ///< Firmware reset to factory defaults + MBG_EVT_ID_UFU_FLASHED, ///< UFU file has been flashed + MBG_EVT_ID_UFU_PROGRESS, ///< UFU flashing is in progress + MBG_EVT_ID_DATABASE_CONNECTED, ///< Database(s) have been (re-)connected + MBG_EVT_ID_NTP_STATE_SYNC, ///< NTP is sync + MBG_EVT_ID_NTP_STATE_NOT_SYNC, ///< NTP not sync + MBG_EVT_ID_FW_OSV, ///< Firmware has been set to OSV N_MBG_EVT_ID }; -#define ENG_EVT_ID_NAME_NONE "No event" -#define ENG_EVT_ID_NAME_POW_UP_RES "Power Up Reset" -#define ENG_EVT_ID_NAME_WDOG_RES "Watchdog Reset" -#define ENG_EVT_ID_NAME_COLD_BOOT "Cold Boot" -#define ENG_EVT_ID_NAME_WARM_BOOT "Warm Boot" -#define ENG_EVT_ID_NAME_NORMAL_OP "Normal Operation" -#define ENG_EVT_ID_NAME_ANT_DISCONN "Antenna Disconn." -#define ENG_EVT_ID_NAME_ANT_SHORT "Ant. Short-Circ." -#define ENG_EVT_ID_NAME_ANT_OK "Antenna OK" -#define ENG_EVT_ID_NAME_LOW_SATS "Few Sats Only" - - -#define MBG_EVT_ID_NAMES_ENG \ -{ \ - ENG_EVT_ID_NAME_NONE, \ - ENG_EVT_ID_NAME_POW_UP_RES, \ - ENG_EVT_ID_NAME_WDOG_RES, \ - ENG_EVT_ID_NAME_COLD_BOOT, \ - ENG_EVT_ID_NAME_WARM_BOOT, \ - ENG_EVT_ID_NAME_NORMAL_OP, \ - ENG_EVT_ID_NAME_ANT_DISCONN, \ - ENG_EVT_ID_NAME_ANT_SHORT, \ - ENG_EVT_ID_NAME_ANT_OK, \ - ENG_EVT_ID_NAME_LOW_SATS \ +#define ENG_EVT_ID_NAME_NONE "No event" +#define ENG_EVT_ID_NAME_POW_UP_RES "Power Up Reset" +#define ENG_EVT_ID_NAME_WDOG_RES "Watchdog Reset" +#define ENG_EVT_ID_NAME_COLD_BOOT "Cold Boot" +#define ENG_EVT_ID_NAME_WARM_BOOT "Warm Boot" +#define ENG_EVT_ID_NAME_NORMAL_OP "Normal Operation" +#define ENG_EVT_ID_NAME_ANT_DISCONN "Antenna Disconn." +#define ENG_EVT_ID_NAME_ANT_SHORT "Ant. Short-Circ." +#define ENG_EVT_ID_NAME_ANT_OK "Antenna OK" +#define ENG_EVT_ID_NAME_LOW_SATS "Few Sats Only" +#define ENG_EVT_ID_NAME_FW_INSTALLED "Firmware installed" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_UNINITIALIZED "PTP state: Uninitialized" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_INITIALIZING "PTP state: Initializing" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_FAULTY "PTP state: Faulty" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_DISABLED "PTP state: Disabled" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_LISTENING "PTP state: Listening" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_PRE_MASTER "PTP state: Pre-Master" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_MASTER "PTP state: Master" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_PASSIVE "PTP state: Passive" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_UNCALIBRATED "PTP state: Uncalibrated" +#define ENG_EVT_ID_NAME_PTP_PORT_STATE_SLAVE "PTP state: Slave" +#define ENG_EVT_ID_NAME_FW_ACTIVATED "Firmware activated" +#define ENG_EVT_ID_NAME_FW_DELETED "Firmware deleted" +#define ENG_EVT_ID_NAME_FW_ROLLBACK "Firmware rollback" +#define ENG_EVT_ID_NAME_UFU_FLASHED "UFU flashed" +#define ENG_EVT_ID_NAME_UFU_PROGRESS "UFU is being transferred..." +#define ENG_EVT_ID_NAME_DATABASE_CONNECTED "Database(s) connected" +#define ENG_EVT_ID_NAME_NTP_STATE_SYNC "NTP state: Sync to system peer" +#define ENG_EVT_ID_NAME_NTP_STATE_NOT_SYNC "NTP state: Not sync" +#define ENG_EVT_ID_NAME_FW_OSV "Firmware set to OSV" + + +#define MBG_EVT_ID_NAMES_ENG \ +{ \ + ENG_EVT_ID_NAME_NONE, \ + ENG_EVT_ID_NAME_POW_UP_RES, \ + ENG_EVT_ID_NAME_WDOG_RES, \ + ENG_EVT_ID_NAME_COLD_BOOT, \ + ENG_EVT_ID_NAME_WARM_BOOT, \ + ENG_EVT_ID_NAME_NORMAL_OP, \ + ENG_EVT_ID_NAME_ANT_DISCONN, \ + ENG_EVT_ID_NAME_ANT_SHORT, \ + ENG_EVT_ID_NAME_ANT_OK, \ + ENG_EVT_ID_NAME_LOW_SATS, \ + ENG_EVT_ID_NAME_FW_INSTALLED, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_UNINITIALIZED, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_INITIALIZING, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_FAULTY, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_DISABLED, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_LISTENING, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_PRE_MASTER, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_MASTER, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_PASSIVE, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_UNCALIBRATED, \ + ENG_EVT_ID_NAME_PTP_PORT_STATE_SLAVE, \ + ENG_EVT_ID_NAME_FW_ACTIVATED, \ + ENG_EVT_ID_NAME_FW_DELETED, \ + ENG_EVT_ID_NAME_FW_ROLLBACK, \ + ENG_EVT_ID_NAME_UFU_FLASHED, \ + ENG_EVT_ID_NAME_UFU_PROGRESS, \ + ENG_EVT_ID_NAME_DATABASE_CONNECTED, \ + ENG_EVT_ID_NAME_NTP_STATE_SYNC, \ + ENG_EVT_ID_NAME_FW_OSV \ } @@ -6747,16 +10463,32 @@ enum MBG_EVT_LVLS * * @anchor MBG_EVENT_CODES @{ */ -#define MBG_EVT_NONE _mbg_mk_evt_code( MBG_EVT_ID_NONE, MBG_EVT_LVL_NONE ) -#define MBG_EVT_POW_UP_RES _mbg_mk_evt_code( MBG_EVT_ID_POW_UP_RES, MBG_EVT_LVL_WARN ) -#define MBG_EVT_WDOG_RES _mbg_mk_evt_code( MBG_EVT_ID_WDOG_RES, MBG_EVT_LVL_CRIT ) -#define MBG_EVT_COLD_BOOT _mbg_mk_evt_code( MBG_EVT_ID_COLD_BOOT, MBG_EVT_LVL_ERR ) -#define MBG_EVT_WARM_BOOT _mbg_mk_evt_code( MBG_EVT_ID_WARM_BOOT, MBG_EVT_LVL_ERR ) -#define MBG_EVT_NORMAL_OP _mbg_mk_evt_code( MBG_EVT_ID_NORMAL_OP, MBG_EVT_LVL_INFO ) -#define MBG_EVT_ANT_DISCONN _mbg_mk_evt_code( MBG_EVT_ID_ANT_DISCONN, MBG_EVT_LVL_CRIT ) -#define MBG_EVT_ANT_SHORT _mbg_mk_evt_code( MBG_EVT_ID_ANT_SHORT, MBG_EVT_LVL_CRIT ) -#define MBG_EVT_ANT_OK _mbg_mk_evt_code( MBG_EVT_ID_ANT_OK, MBG_EVT_LVL_INFO ) -#define MBG_EVT_LOW_SATS _mbg_mk_evt_code( MBG_EVT_ID_LOW_SATS, MBG_EVT_LVL_WARN ) +#define MBG_EVT_NONE _mbg_mk_evt_code( MBG_EVT_ID_NONE, MBG_EVT_LVL_NONE ) +#define MBG_EVT_POW_UP_RES _mbg_mk_evt_code( MBG_EVT_ID_POW_UP_RES, MBG_EVT_LVL_WARN ) +#define MBG_EVT_WDOG_RES _mbg_mk_evt_code( MBG_EVT_ID_WDOG_RES, MBG_EVT_LVL_CRIT ) +#define MBG_EVT_COLD_BOOT _mbg_mk_evt_code( MBG_EVT_ID_COLD_BOOT, MBG_EVT_LVL_ERR ) +#define MBG_EVT_WARM_BOOT _mbg_mk_evt_code( MBG_EVT_ID_WARM_BOOT, MBG_EVT_LVL_ERR ) +#define MBG_EVT_NORMAL_OP _mbg_mk_evt_code( MBG_EVT_ID_NORMAL_OP, MBG_EVT_LVL_INFO ) +#define MBG_EVT_ANT_DISCONN _mbg_mk_evt_code( MBG_EVT_ID_ANT_DISCONN, MBG_EVT_LVL_CRIT ) +#define MBG_EVT_ANT_SHORT _mbg_mk_evt_code( MBG_EVT_ID_ANT_SHORT, MBG_EVT_LVL_CRIT ) +#define MBG_EVT_ANT_OK _mbg_mk_evt_code( MBG_EVT_ID_ANT_OK, MBG_EVT_LVL_INFO ) +#define MBG_EVT_LOW_SATS _mbg_mk_evt_code( MBG_EVT_ID_LOW_SATS, MBG_EVT_LVL_WARN ) +#define MBG_EVT_FW_INSTALLED _mbg_mk_evt_code( MBG_EVT_ID_FW_INSTALLED, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_UNINITIALIZED _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_UNINITIALIZED, MBG_EVT_LVL_WARN ) +#define MBG_EVT_PTP_PORT_STATE_INITIALIZING _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_INITIALIZING, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_FAULTY _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_FAULTY, MBG_EVT_LVL_ERR ) +#define MBG_EVT_PTP_PORT_STATE_DISABLED _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_DISABLED, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_LISTENING _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_LISTENING, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_PRE_MASTER _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_PRE_MASTER, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_MASTER _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_MASTER, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_PASSIVE _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_PASSIVE, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_UNCALIBRATED _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_UNCALIBRATED, MBG_EVT_LVL_INFO ) +#define MBG_EVT_PTP_PORT_STATE_SLAVE _mbg_mk_evt_code( MBG_EVT_ID_PTP_PORT_STATE_SLAVE, MBG_EVT_LVL_INFO ) +#define MBG_EVT_FW_ACTIVATED _mbg_mk_evt_code( MBG_EVT_ID_FW_ACTIVATED, MBG_EVT_LVL_INFO ) +#define MBG_EVT_DATABASE_CONNECTED _mbg_mk_evt_code( MBG_EVT_ID_DATABASE_CONNTECTED, MBG_EVT_LVL_INFO ) +#define MBG_EVT_NTP_STATE_SYNC _mbg_mk_evt_code( MBG_EVT_ID_NTP_STATE_SYNC, MBG_EVT_LVL_INFO ) +#define MBG_EVT_NTP_STATE_NOT_SYNC _mbg_mk_evt_code( MBG_EVT_ID_NTP_STATE_NOT_SYNC, MBG_EVT_LVL_WARN ) +#define MBG_EVT_FW_OSV _mbg_mk_evt_code( MBG_EVT_ID_FW_OSV, MBG_EVT_LVL_INFO ) /** @} anchor MBG_EVENT_CODES */ @@ -6774,29 +10506,54 @@ enum MBG_EVT_LVLS /** * @brief Generic state of an IMS device */ -typedef struct +typedef struct mbg_ims_state_s { uint8_t chassis_id; ///< chassis ID, 0 if installed on the backplane uint8_t slot_id; ///< slot number on the chassis uint16_t num_sensors; ///< number of sensors provided by the device uint32_t reserved; ///< reserved, currently always 0 - uint32_t flags; ///< unused, currently always 0 + uint32_t flags; ///< See ::MBG_IMS_STATE_FLAG_MASKS } MBG_IMS_STATE; #define _mbg_swab_mbg_ims_state( _p ) \ +do \ { \ _mbg_swab16( &(_p)->num_sensors ); \ _mbg_swab32( &(_p)->reserved ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) + + + +/** + * @brief Enumeration of bits used to define ::MBG_IMS_STATE_FLAG_MASKS + * + * @see ::MBG_IMS_STATE_FLAG_MASKS + */ +enum MBG_IMS_STATE_FLAG_BITS +{ + MBG_IMS_STATE_FLAG_BIT_HAS_FDM, ///< device supports FDM API + N_MBG_IMS_STATE_FLAG_BITS +}; + + +/** + * @brief Bit masks used with ::MBG_IMS_STATE::flags + * + * @see ::MBG_IMS_STATE_FLAG_BITS + */ +enum MBG_IMS_STATE_FLAG_MASKS +{ + MBG_IMS_STATE_FLAG_MSK_HAS_FDM = ( 1UL << MBG_IMS_STATE_FLAG_BIT_HAS_FDM ) ///< See ::MBG_IMS_STATE_FLAG_BIT_HAS_FDM +}; /** * @brief Generic state of an IMS sensor */ -typedef struct +typedef struct mbg_ims_sensor_state_s { uint16_t type; ///< sensor type, see ::MBG_IMS_SENSORS uint16_t idx; ///< index of the sensor of this type @@ -6808,6 +10565,7 @@ typedef struct } MBG_IMS_SENSOR_STATE; #define _mbg_swab_mbg_ims_sensor_state( _p ) \ +do \ { \ _mbg_swab16( &(_p)->type ); \ _mbg_swab16( &(_p)->idx ); \ @@ -6815,7 +10573,7 @@ typedef struct _mbg_swab16( &(_p)->exp ); \ _mbg_swab16( &(_p)->reserved ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) /** @@ -6823,41 +10581,474 @@ typedef struct */ typedef struct { - uint32_t idx; ///< sensor index, 0..::MBG_IMS_STATE::num_sensors-1 + MBG_MSG_IDX_32 idx; ///< sensor index, 0..::MBG_IMS_STATE::num_sensors-1 MBG_IMS_SENSOR_STATE state; ///< sensor state } MBG_IMS_SENSOR_STATE_IDX; #define _mbg_swab_mbg_ims_sensor_state_idx( _p ) \ +do \ { \ _mbg_swab32( &(_p)->idx ); \ _mbg_swab_mbg_ims_sensor_state( &(_p)->state ); \ -} +} while ( 0 ) /** * @brief IMS sensor types + * + * Used with ::MBG_IMS_SENSOR_STATE::type */ enum MBG_IMS_SENSORS { - MBG_IMS_SENSOR_TEMP_C, ///< temperature in degrees Celsius - MBG_IMS_SENSOR_VOLTAGE, ///< voltage in val/exp, output state in flags - MBG_IMS_SENSOR_PLL, ///< control voltage in val/exp, lock state in flags - N_MBG_IMS_SENSORS ///< number of supported sensor types + MBG_IMS_SENSOR_TEMP_C, ///< temperature in degrees Celsius + MBG_IMS_SENSOR_VOLTAGE, ///< voltage in val/exp, output state in flags + MBG_IMS_SENSOR_PLL, ///< control voltage in val/exp, lock state in flags + MBG_IMS_SENSOR_VOLTAGE_INPUT, ///< input voltage in val/exp, output state in flags + MBG_IMS_SENSOR_VOLTAGE_OUTPUT, ///< output voltage in val/exp, output state in flags + MBG_IMS_SENSOR_VOLTAGE_SUPPLY, ///< supply voltage in val/exp, output state in flags + MBG_IMS_SENSOR_CURRENT, ///< generic current in val/exp, output state in flags + MBG_IMS_SENSOR_CURRENT_BOARD_SUPPLY, ///< board supply current in val/exp, output state in flags + MBG_IMS_SENSOR_CURRENT_OSC_SUPPLY, ///< oscillator supply current in val/exp, output state in flags + N_MBG_IMS_SENSORS ///< number of supported sensor types +}; + + + +/** + * @brief IMS sensor state flags for voltage + * + * Used with ::MBG_IMS_SENSOR_STATE::flags in case ::MBG_IMS_SENSOR_STATE::type + * is ::MBG_IMS_SENSOR_VOLTAGE. + */ +enum MBG_IMS_SENSOR_STATE_FLAG_MASK_VOLTAGE +{ + MBG_IMS_SENSOR_VOLTAGE_OUT_ENB = 0x01, ///< output is enabled + MBG_IMS_SENSOR_VOLTAGE_OUT_OVR = 0x02 ///< output overload +}; + + +/** + * @brief IMS sensor state flags for PLL + * + * Used with ::MBG_IMS_SENSOR_STATE::flags in case ::MBG_IMS_SENSOR_STATE::type + * is ::MBG_IMS_SENSOR_PLL. + */ +enum MBG_IMS_SENSOR_STATE_FLAG_MASK_PLL +{ + MBG_IMS_SENSOR_PLL_LOCKED = 0x01 ///< PLL is locked +}; + + + +/** + * @brief DAC limit specs + */ +typedef struct +{ + int32_t dac_val_min; ///< min. possible DAC Value, positive or negative + int32_t dac_val_max; ///< max. possible DAC Value, positive or negative + + int32_t u_min; ///< min. possible real voltage range [mV], positive or negative, depending on ::MBG_DAC_SPECS::dac_val_min + int32_t u_max; ///< max. possible real voltage range [mV], positive or negative, depending on ::MBG_DAC_SPECS::dac_val_max + + uint32_t reserved_0; ///< reserved, currently always 0 + uint32_t reserved_1; ///< reserved, currently always 0 + +} MBG_DAC_SPECS; + +#define _mbg_swab_mbg_dac_specs( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->dac_val_min ); \ + _mbg_swab32( &(_p)->dac_val_max ); \ + _mbg_swab32( &(_p)->u_min ); \ + _mbg_swab32( &(_p)->u_max ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Output state of FDM device. + * + * @note This is only supported if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + */ +typedef struct mbg_ims_fdm_output_state_s +{ + int32_t dac_val; ///< current DAC value, positive or negative + uint32_t mode; ///< current output mode, see ::MBG_IMS_FDM_OUTPUT_MODES + + MBG_DAC_SPECS dac_specs; ///< DAC specific limits + + uint32_t reserved_0; ///< reserved, currently always 0 + uint32_t reserved_1; ///< reserved, currently always 0 + +} MBG_IMS_FDM_OUTPUT_STATE; + +#define _mbg_swab_mbg_ims_fdm_output_state( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->dac_val ); \ + _mbg_swab32( &(_p)->mode ); \ + _mbg_swab_mbg_dac_specs( &(_p)->dac_specs ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Output state of FDM device plus index. + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_IMS_FDM_OUTPUT_STATE state; + +} MBG_IMS_FDM_OUTPUT_STATE_IDX; + +#define _mbg_swab_mbg_ims_fdm_output_state_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_ims_fdm_output_state( &(_p)->state ); \ +} while ( 0 ) + + + +/** + * @brief Output settings of FDM device + * + * @note This is only supported if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags + */ +typedef struct +{ + uint32_t mode; ///< mode, see ::MBG_IMS_FDM_OUTPUT_MODES + uint32_t reserved; ///< reserved, currently always 0 + +} MBG_IMS_FDM_OUTPUT_SETTINGS; + +#define _mbg_swab_mbg_ims_fdm_output_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->mode ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + + +/** + * @brief Output settings for FDM devices plus index. + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_IMS_FDM_OUTPUT_SETTINGS settings; + +} MBG_IMS_FDM_OUTPUT_SETTINGS_IDX; + +#define _mbg_swab_mbg_ims_fdm_output_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_ims_fdm_output_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Specific output settings and limits. + */ +typedef struct mbg_ims_fdm_output_info_s +{ + MBG_IMS_FDM_OUTPUT_SETTINGS settings; ///< current settings + uint32_t supp_modes; ///< supported modes, see ::MBG_IMS_FDM_OUTPUT_MODE_MASKS + MBG_DAC_SPECS dac_specs; ///< DAC specific limits + +} MBG_IMS_FDM_OUTPUT_INFO; + +#define _mbg_swab_mbg_ims_fdm_output_info( _p ) \ +do \ +{ \ + _mbg_swab_mbg_ims_fdm_output_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab_mbg_dac_specs( &(_p)->dac_specs ); \ +} while ( 0 ) + + + +/** + * @brief Specific output settings and limits, plus index. + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_IMS_FDM_OUTPUT_INFO info; + +} MBG_IMS_FDM_OUTPUT_INFO_IDX; + +#define _mbg_swab_mbg_ims_fdm_output_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_mbg_ims_fdm_output_info( &(_p)->info ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of known output modes + * + * Used with ::MBG_IMS_FDM_OUTPUT_STATE::mode + * + * @see ::MBG_IMS_FDM_OUTPUT_MODE_MASKS + */ +enum MBG_IMS_FDM_OUTPUT_MODES +{ + MBG_IMS_FDM_OUTPUT_MODE_FD, ///< Analog output reflects frequency deviation + MBG_IMS_FDM_OUTPUT_MODE_TD, ///< Analog output reflects time deviation + N_MBG_IMS_FDM_OUTPUT_MODES ///< Number of known output modes +}; + + + +/** + * @brief Bit masks used with ::MBG_IMS_FDM_OUTPUT_STATE::mode + * + * @see ::MBG_IMS_FDM_OUTPUT_MODES + */ +enum MBG_IMS_FDM_OUTPUT_MODE_MASKS +{ + MBG_IMS_FDM_OUTPUT_MODE_MSK_FD = ( 1UL << MBG_IMS_FDM_OUTPUT_MODE_FD ), ///< See ::MBG_IMS_FDM_OUTPUT_MODE_FD + MBG_IMS_FDM_OUTPUT_MODE_MSK_TD = ( 1UL << MBG_IMS_FDM_OUTPUT_MODE_TD ) ///< See ::MBG_IMS_FDM_OUTPUT_MODE_TD +}; + + + +/** + * @brief A generic structure used to specify FDM limits + */ +typedef struct mbg_ims_fdm_limits_s +{ + uint8_t n_outputs; ///< number of outputs per module + uint8_t reserved_0; ///< reserved, currently always 0 + uint16_t reserved_1; ///< reserved, currently always 0 + + uint32_t fd_neg_limit; ///< min. frequency deviation limit, 1/::MBG_IMS_FDM_LIMITS::fd_scale Hz units + uint32_t fd_pos_limit; ///< max. frequency deviation limit, 1/::MBG_IMS_FDM_LIMITS::fd_scale Hz units + uint32_t fd_scale; ///< scale for ::MBG_IMS_FDM_LIMITS::fd_neg_limit and ::MBG_IMS_FDM_LIMITS::fd_pos_limit + + uint32_t td_neg_limit; ///< min. time deviation limit, 1/::MBG_IMS_FDM_LIMITS::td_scale s units + uint32_t td_pos_limit; ///< max. time deviation limit, 1/::MBG_IMS_FDM_LIMITS::td_scale s units + uint32_t td_scale; ///< scale for ::MBG_IMS_FDM_LIMITS::td_neg_limit and ::MBG_IMS_FDM_LIMITS::td_pos_limit + + uint32_t reserved_2; ///< reserved, currently always 0 + +} MBG_IMS_FDM_LIMITS; + +#define _mbg_swab_mbg_ims_fdm_limits( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->n_outputs ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + \ + _mbg_swab32( &(_p)->fd_neg_limit ); \ + _mbg_swab32( &(_p)->fd_pos_limit ); \ + _mbg_swab32( &(_p)->fd_scale ); \ + \ + _mbg_swab32( &(_p)->td_neg_limit ); \ + _mbg_swab32( &(_p)->td_pos_limit ); \ + _mbg_swab32( &(_p)->td_scale ); \ + \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +/** + * @brief State of FDM device + * + * @note This is only supported if ::MBG_IMS_STATE_FLAG_MSK_HAS_FDM is set in ::MBG_IMS_STATE::flags. + * + */ +typedef struct mbg_ims_fdm_state_s +{ + MBG_GPIO_FREQ freq; ///< Current frequency + + NANO_TIME_64 t_ref; ///< Current reference time + NANO_TIME_64 t_plt; ///< Current power line time + NANO_TIME_64 t_sync; ///< Last sync Time (reference time) + + uint32_t line_freq; ///< Nominal line frequency, see ::MBG_IMS_FDM_LINE_FREQS + uint32_t flags; ///< Flags, see ::MBG_IMS_FDM_STATE_FLAG_MASKS + uint32_t reserved; ///< Reserved, currently always 0 + +} MBG_IMS_FDM_STATE; + +#define _mbg_swab_mbg_ims_fdm_state( _p ) \ +do \ +{ \ + _mbg_swab_mbg_gpio_freq( &(_p)->freq ); \ + _mbg_swab_nano_time_64( &(_p)->t_ref ); \ + _mbg_swab_nano_time_64( &(_p)->t_plt ); \ + _mbg_swab_nano_time_64( &(_p)->t_sync ); \ + _mbg_swab32( &(_p)->line_freq ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration known line frequencies + * + * Used with ::MBG_IMS_FDM_STATE::line_freq + * + * @see ::MBG_IMS_FDM_LINE_FREQ_MASKS + */ +enum MBG_IMS_FDM_LINE_FREQS +{ + MBG_IMS_FDM_LINE_FREQ_AUTO, ///< Auto detect line frequency + MBG_IMS_FDM_LINE_FREQ_50HZ, ///< 50Hz line frequency + MBG_IMS_FDM_LINE_FREQ_60HZ, ///< 60Hz line frequency + N_MBG_IMS_FDM_LINE_FREQS ///< number of known line frequencies +}; + + +/** + * @brief Bit masks corresponding to defined line frequencies + * + * @see ::MBG_IMS_FDM_LINE_FREQS + */ +enum MBG_IMS_FDM_LINE_FREQ_MASKS +{ + MBG_IMS_FDM_LINE_FREQ_MSK_AUTO = ( 1UL << MBG_IMS_FDM_LINE_FREQ_AUTO ), ///< See ::MBG_IMS_FDM_LINE_FREQ_AUTO + MBG_IMS_FDM_LINE_FREQ_MSK_50HZ = ( 1UL << MBG_IMS_FDM_LINE_FREQ_50HZ ), ///< See ::MBG_IMS_FDM_LINE_FREQ_50HZ + MBG_IMS_FDM_LINE_FREQ_MSK_60HZ = ( 1UL << MBG_IMS_FDM_LINE_FREQ_60HZ ) ///< See ::MBG_IMS_FDM_LINE_FREQ_60HZ +}; + + +/** + * @brief Initializers for an array of line freq. name strings + * + * @see ::MBG_IMS_FDM_LINE_FREQS + */ +#define MBG_IMS_FDM_LINE_FREQ_STRS \ +{ \ + "Auto", \ + "50 Hz", \ + "60 Hz", \ +} + + +/** + * @brief Enumeration of flag bits used to define ::MBG_IMS_FDM_STATE_FLAG_MASKS + */ +enum MBG_IMS_FDM_STATE_FLAG_BITS +{ + MBG_IMS_FDM_STATE_FLAG_BIT_SYNC_AFTER_RESET, ///< if sync'ed after reset + MBG_IMS_FDM_STATE_FLAG_BIT_PLT_IS_LOCKED, ///< Power Line Time is locked + MBG_IMS_FDM_STATE_FLAG_BIT_FD_OVERFLOW, ///< Frequency deviation overflow occurred + MBG_IMS_FDM_STATE_FLAG_BIT_TD_OVERFLOW, ///< Time deviation overflow occurred + N_MBG_IMS_FDM_STATE_FLAG_BITS ///< number of known state flag bits +}; + + +/** + * @brief Bit masks used with ::MBG_IMS_FDM_STATE::flags + * + * @see ::MBG_IMS_FDM_STATE_FLAG_BITS + */ +enum MBG_IMS_FDM_STATE_FLAG_MASKS +{ + MBG_IMS_FDM_STATE_FLAG_MSK_SYNC_AFTER_RESET = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_SYNC_AFTER_RESET ), ///< See ::MBG_IMS_FDM_STATE_FLAG_BIT_SYNC_AFTER_RESET + MBG_IMS_FDM_STATE_FLAG_MSK_PLT_IS_LOCKED = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_PLT_IS_LOCKED ), ///< See ::MBG_IMS_FDM_STATE_FLAG_BIT_PLT_IS_LOCKED + MBG_IMS_FDM_STATE_FLAG_MSK_FD_OVERFLOW = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_FD_OVERFLOW ), ///< See ::MBG_IMS_FDM_STATE_FLAG_BIT_FD_OVERFLOW + MBG_IMS_FDM_STATE_FLAG_MSK_TD_OVERFLOW = ( 1UL << MBG_IMS_FDM_STATE_FLAG_BIT_TD_OVERFLOW ) ///< See ::MBG_IMS_FDM_STATE_FLAG_BIT_TD_OVERFLOW }; -// Definitions used with ::MBG_IMS_SENSOR_STATE::flags: +/** + * @brief FDM device settings + * + * @note This is only supported if ::MBG_IMS_STATE_FLAG_BIT_HAS_FDM is set in ::MBG_IMS_STATE::flags. + * + */ +typedef struct +{ + uint32_t fd_neg_limit; ///< min. frequency deviation limit in 1 mHz steps + uint32_t fd_pos_limit; ///< max. frequency deviation limit in 1 mHz steps -// if ::MBG_IMS_SENSOR_STATE::type == ::MBG_IMS_SENSOR_VOLTAGE -#define MBG_IMS_SENSOR_VOLTAGE_OUT_ENB 0x01 // output is enabled -#define MBG_IMS_SENSOR_VOLTAGE_OUT_OVR 0x02 // output overload + uint32_t td_neg_limit; ///< min. time deviation limit in 1 ms steps + uint32_t td_pos_limit; ///< max. time deviation limit in 1 ms steps -// if ::MBG_IMS_SENSOR_STATE::type == ::MBG_IMS_SENSOR_PLL -#define MBG_IMS_SENSOR_PLL_LOCKED 0x01 + uint32_t line_freq; ///< nominal line frequency, see ::MBG_IMS_FDM_LINE_FREQS + uint32_t reserved; ///< reserved, currently always 0 +} MBG_IMS_FDM_SETTINGS; + +#define _mbg_swab_mbg_ims_fdm_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->fd_neg_limit ); \ + _mbg_swab32( &(_p)->fd_pos_limit ); \ + _mbg_swab32( &(_p)->td_neg_limit ); \ + _mbg_swab32( &(_p)->td_pos_limit ); \ + _mbg_swab32( &(_p)->line_freq ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + + + +/** + * @brief IMS FDM flags + * + * @see ::MBG_IMS_FDM_FLAG_MASKS + */ +enum MBG_IMS_FDM_FLAGS +{ + MBG_IMS_FDM_FLAG_CAN_SET_TDEV, ///< Device supports command GPS_FDM_SET_TD + N_MBG_IMS_FDM_FLAGS ///< Number of known FDM flags +}; + + + +/** + * @brief IMS FDM flag masks + * + * @see ::MBG_IMS_FDM_FLAGS + */ +enum MBG_IMS_FDM_FLAG_MASKS +{ + MBG_IMS_FDM_FLAG_MASK_CAN_SET_TDEV = ( 1UL << MBG_IMS_FDM_FLAG_CAN_SET_TDEV ) ///< See ::MBG_IMS_FDM_FLAG_CAN_SET_TDEV +}; + + + +/** + * @brief Specific FDM settings and limits. + */ +typedef struct mbg_ims_fdm_info_s +{ + MBG_IMS_FDM_SETTINGS settings; + uint32_t supp_line_freqs; ///< Bit mask of supported line frequencies, see ::MBG_IMS_FDM_LINE_FREQ_MASKS + uint32_t reserved; ///< Reserved, currently always 0 + uint32_t flags; ///< Flags, see ::MBG_IMS_FDM_FLAG_MASKS + +} MBG_IMS_FDM_INFO; + +#define _mbg_swab_mbg_ims_fdm_info( _p ) \ +do \ +{ \ + _mbg_swab_mbg_ims_fdm_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_line_freqs ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) /** @} defgroup group_ims */ @@ -6897,10 +11088,11 @@ typedef struct } GEN_IO_INFO; #define _mbg_swab_gen_io_info( _p ) \ +do \ { \ _mbg_swab_gen_io_info_type( &(_p)->type ); \ _mbg_swab16( &(_p)->num ); \ -} +} while ( 0 ) @@ -6980,6 +11172,19 @@ typedef struct } SCU_STAT_INFO; +#define _mbg_swab_scu_stat_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->hw_id ); \ + _mbg_swab32( &(_p)->fw_id ); \ + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab8( &(_p)->clk0_info ); \ + _mbg_swab8( &(_p)->clk1_info ); \ + _mbg_swab16( &(_p)->epld_status ); \ + _mbg_swab16( &(_p)->epld_control ); \ +} while ( 0 ) + + typedef struct { @@ -6989,6 +11194,15 @@ typedef struct } SCU_STAT_SETTINGS; +#define _mbg_swab_scu_stat_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->epld_control_mask ); \ + _mbg_swab16( &(_p)->epld_control_value ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + /** * @brief Bit masks used to check the SCU EPLD status @@ -6997,17 +11211,22 @@ typedef struct */ enum SCU_STAT_MASKS { - MSK_EPLD_STAT_TS1 = 0x0001, ///< state of time sync signal clk_1 - MSK_EPLD_STAT_TS2 = 0x0002, ///< state of time sync signal clk_2 - MSK_EPLD_STAT_TL_ERROR = 0x0004, ///< state of time limit error input - MSK_EPLD_STAT_PSU1_OK = 0x0008, ///< state of power supply 1 monitoring input - MSK_EPLD_STAT_PSU2_OK = 0x0010, ///< state of power supply 2 monitoring input - MSK_EPLD_STAT_AUTO = 0x0020, ///< AUTOMATIC/REMOTE or MANUAL Mode - MSK_EPLD_STAT_SEL = 0x0040, ///< select bit for output MUX, ( clk_1 = 0 ) - MSK_EPLD_STAT_ENA = 0x0080, ///< enable Bit for output MUX, set if enabled - - MSK_EPLD_STAT_ACO = 0x4000, ///< Access control override bit - MSK_EPLD_STAT_WDOG_OK = 0x8000 ///< WDT_OK set to zero if watchdog expired + MSK_EPLD_STAT_TS1 = 0x0001, ///< state of time sync signal clk_1 + MSK_EPLD_STAT_TS2 = 0x0002, ///< state of time sync signal clk_2 + MSK_EPLD_STAT_TL_ERROR = 0x0004, ///< state of time limit error input + MSK_EPLD_STAT_PSU1_OK = 0x0008, ///< state of power supply 1 monitoring input + MSK_EPLD_STAT_PSU2_OK = 0x0010, ///< state of power supply 2 monitoring input + MSK_EPLD_STAT_AUTO = 0x0020, ///< AUTOMATIC/REMOTE or MANUAL Mode + MSK_EPLD_STAT_SEL = 0x0040, ///< select bit for output MUX, ( clk_1 = 0 ) + MSK_EPLD_STAT_ENA = 0x0080, ///< enable Bit for output MUX, set if enabled + MSK_EPLD_STAT_HAS_LAN = 0x0100, ///< indicates that the device has a network interface + MSK_EPLD_STAT_RESERVED0 = 0x0200, ///< reserved, DO NOT USE! + MSK_EPLD_STAT_RESERVED1 = 0x0400, ///< reserved, DO NOT USE! + MSK_EPLD_STAT_HAS_4_PSUS = 0x0800, ///< indicates 4 power supplies instead of 2 + MSK_EPLD_STAT_PSU3_OK = 0x1000, ///< state of power supply 3 monitoring input + MSK_EPLD_STAT_PSU4_OK = 0x2000, ///< state of power supply 4 monitoring input + MSK_EPLD_STAT_ACO = 0x4000, ///< Access control override bit + MSK_EPLD_STAT_WDOG_OK = 0x8000 ///< WDT_OK set to zero if watchdog expired }; @@ -7081,14 +11300,14 @@ enum RECEIVER_MODES typedef int16_t DAC_VAL; #define _mbg_swab_dac_val( _p ) \ - _mbg_swab16( _p ); + _mbg_swab16( _p ) /** * @brief Satellite receiver status information */ -typedef struct +typedef struct stat_info_s { uint16_t mode; ///< Mode of operation, see ::RECEIVER_MODES uint16_t good_svs; ///< Numb. of satellites that can currently be received and used @@ -7099,13 +11318,14 @@ typedef struct } STAT_INFO; #define _mbg_swab_stat_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->mode ); \ _mbg_swab16( &(_p)->good_svs ); \ _mbg_swab16( &(_p)->svs_in_view ); \ _mbg_swab_dac_val( &(_p)->dac_val ); \ _mbg_swab_dac_val( &(_p)->dac_cal ); \ -} +} while ( 0 ) #define OSC_DAC_RANGE 4096UL @@ -7114,6 +11334,90 @@ typedef struct /** + * @brief Bit masks for a legacy GPS SV status. + * + * Used with ::SV_INFO::stat_flags. + */ +enum SV_STAT_FLAG_MASKS +{ + SV_EXISTS = 0x0001, ///< The SV exists physically. + SV_IS_IN_VIEW = 0x0002, ///< SV should be visible at this moment. + SV_CAN_BE_RECEIVED = 0x0004, ///< SV can be tracked. + SV_MIGHT_BE_USED = 0x0008 ///< SV might be used. +}; + +/** + * @brief A combination of ::SV_STAT_FLAG_MASKS indicating an SV is "good". + * + * Used with ::SV_INFO::stat_flags. + */ +#define SV_IS_GOOD ( SV_EXISTS | SV_IS_IN_VIEW | SV_CAN_BE_RECEIVED | SV_MIGHT_BE_USED ) + + + +/** + * @brief A legacy satellite info structure. + * + * Used with pure GPS receivers. Newer GNSS receivers should + * support the ::GNSS_SV_STATUS structure. + * + * @see ::GNSS_SV_STATUS + */ +typedef struct sv_info_s +{ + SVNO svno; ///< The satellite number, ::MIN_SVNO_GPS...::MAX_SVNO_GPS. + int16_t stat_flags; ///< See ::SV_STAT_FLAG_MASKS. + int16_t elev; ///< Elevetion of the satellite [degrees]. + int16_t azim; ///< Azimuth of the satellite [degrees]. + int16_t doppler; ///< Doppler frequency of the satellite [Hz]. + int32_t est_dly; ///< Estimated signal propagation delay [100 ns units]. + int32_t cap_dly; ///< Measured signal propagation delay [100 ns units]. + +} SV_INFO; + + + +/** + * @brief Information on usage of a receiver channel. + * + * Used with pure GPS receivers. + * + * @note Very old GPS receivers which supported only 5 channels + * provided the ::CHANNEL_5 structure instead. + * + * @see ::CHANNEL_5 + */ +typedef struct +{ + int8_t num; ///< The receiver channel index, starting at 0. + int8_t svno; ///< The satellite number, ::MIN_SVNO_GPS...::MAX_SVNO_GPS. + int16_t doppler; ///< Doppler frequency of the satellite [Hz]. + int16_t elev; ///< Elevetion of the satellite [degrees]. + int16_t status; ///< 1: synchronized to data stream from satellite, else 0. + +} CHANNEL; + + + +/** + * @brief Information on usage of a receiver channel. + * + * Very old GPS receivers which supported only 5 channels + * provided this structure instead of the ::CHANNEL structure. + * + * @see ::CHANNEL + */ +typedef struct +{ + int8_t num; ///< The receiver channel index, starting at 0. + int8_t svno; ///< The satellite number, ::MIN_SVNO_GPS...::MAX_SVNO_GPS. + int16_t status; ///< 1: synchronized to data stream from satellite, else 0. + +} CHANNEL_5; + + + +/** * @brief An enumeration of known satellite navigation systems * * @see ::MBG_GNSS_TYPE_MASKS @@ -7127,6 +11431,7 @@ enum MBG_GNSS_TYPES GNSS_TYPE_GALILEO, ///< GALILEO, Europe GNSS_TYPE_WAAS, ///< WAAS, Wide Area Augmentation System GNSS_TYPE_EGNOS, ///< EGNOS, European Geostationary Navigation Overlay Service + GNSS_TYPE_QZSS, ///< QZSS, Quasi Zenith Satellite System N_GNSS_TYPES ///< Number of defined codes }; @@ -7138,12 +11443,13 @@ enum MBG_GNSS_TYPES */ enum MBG_GNSS_TYPE_MASKS { - MBG_GNSS_TYPE_MSK_GPS = ( 1UL << GNSS_TYPE_GPS ), ///< see ::GNSS_TYPE_GPS - MBG_GNSS_TYPE_MSK_GLONASS = ( 1UL << GNSS_TYPE_GLONASS ), ///< see ::GNSS_TYPE_GLONASS - MBG_GNSS_TYPE_MSK_BEIDOU = ( 1UL << GNSS_TYPE_BEIDOU ), ///< see ::GNSS_TYPE_BEIDOU - MBG_GNSS_TYPE_MSK_GALILEO = ( 1UL << GNSS_TYPE_GALILEO ), ///< see ::GNSS_TYPE_GALILEO - MBG_GNSS_TYPE_MSK_WAAS = ( 1UL << GNSS_TYPE_WAAS ), ///< see ::GNSS_TYPE_WAAS - MBG_GNSS_TYPE_MSK_EGNOS = ( 1UL << GNSS_TYPE_EGNOS ) ///< see ::GNSS_TYPE_EGNOS + MBG_GNSS_TYPE_MSK_GPS = ( 1UL << GNSS_TYPE_GPS ), ///< See ::GNSS_TYPE_GPS + MBG_GNSS_TYPE_MSK_GLONASS = ( 1UL << GNSS_TYPE_GLONASS ), ///< See ::GNSS_TYPE_GLONASS + MBG_GNSS_TYPE_MSK_BEIDOU = ( 1UL << GNSS_TYPE_BEIDOU ), ///< See ::GNSS_TYPE_BEIDOU + MBG_GNSS_TYPE_MSK_GALILEO = ( 1UL << GNSS_TYPE_GALILEO ), ///< See ::GNSS_TYPE_GALILEO + MBG_GNSS_TYPE_MSK_WAAS = ( 1UL << GNSS_TYPE_WAAS ), ///< See ::GNSS_TYPE_WAAS + MBG_GNSS_TYPE_MSK_EGNOS = ( 1UL << GNSS_TYPE_EGNOS ), ///< See ::GNSS_TYPE_EGNOS + MBG_GNSS_TYPE_MSK_QZSS = ( 1UL << GNSS_TYPE_QZSS ) ///< See ::GNSS_TYPE_QZSS }; @@ -7159,7 +11465,8 @@ enum MBG_GNSS_TYPE_MASKS "BEIDOU", \ "GALILEO", \ "WAAS", \ - "EGNOS" \ + "EGNOS", \ + "QZSS" \ } @@ -7173,70 +11480,77 @@ enum MBG_GNSS_TYPE_MASKS typedef struct { uint32_t gnss_set; ///< bit mask of currently used GNSS systems, see ::MBG_GNSS_TYPE_MASKS - uint8_t prio[N_GNSS_MODE_PRIO]; ///< see ::MBG_GNSS_TYPES, unused fields set to 0xFF, idx 0 is highest prio - uint32_t flags; ///< see ::MBG_GNSS_MODE_FLAG_MASKS + uint8_t prio[N_GNSS_MODE_PRIO]; ///< See ::MBG_GNSS_TYPES, unused fields set to 0xFF, idx 0 is highest prio + uint32_t flags; ///< unused, currently always 0 (should be named MBG_GNSS_MODE_SETTINGS_FLAG_MASKS) } MBG_GNSS_MODE_SETTINGS; #define _mbg_swab_mbg_gnss_mode_settings( _p ) \ +do \ { \ _mbg_swab32( &(_p)->gnss_set ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) typedef struct { - MBG_GNSS_MODE_SETTINGS settings; ///< current GNSS mode settings - uint32_t supp_gnss_types; ///< bit masks of supported GNSS types, see ::MBG_GNSS_TYPE_MASKS - uint32_t flags; ///< indicates which flags are supported for settings::flags, see ::MBG_GNSS_MODE_FLAG_MASKS + MBG_GNSS_MODE_SETTINGS settings; ///< Current GNSS mode settings + uint32_t supp_gnss_types; ///< Bit masks of supported GNSS types, see ::MBG_GNSS_TYPE_MASKS + uint16_t flags; ///< See ::MBG_GNSS_MODE_INFO_FLAG_MASKS + uint16_t n_sv_status; ///< Number of ::GNSS_SV_STATUS_IDX structures that can be read (only if ::MBG_GNSS_FLAG_MSK_HAS_SV_STATUS) } MBG_GNSS_MODE_INFO; #define _mbg_swab_mbg_gnss_mode_info( _p ) \ +do \ { \ _mbg_swab_mbg_gnss_mode_settings( &(_p)->settings ); \ _mbg_swab32( &(_p)->supp_gnss_types ); \ - _mbg_swab32( &(_p)->flags ); \ -} + _mbg_swab16( &(_p)->flags ); \ + _mbg_swab16( &(_p)->n_sv_status ); \ +} while ( 0 ) /** - * @brief Flag bits used with ::MBG_GNSS_MODE_SETTINGS and ::MBG_GNSS_MODE_INFO + * @brief Flag bits used to define ::MBG_GNSS_MODE_INFO_FLAG_MASKS * - * @see ::MBG_GNSS_MODE_FLAG_MASKS + * @see ::MBG_GNSS_MODE_INFO_FLAG_MASKS */ -enum MBG_GNSS_MODE_FLAG_BITS +enum MBG_GNSS_MODE_INFO_FLAG_BITS { - MBG_GNSS_FLAG_EXCLUSIVE, ///< (read only) only one of the supported GNSS systems can be used at the same time - MBG_GNSS_FLAG_HAS_PRIORITY, ///< (read only) priority can be configured using the MBG_GNSS_MODE_SETTINGS::prio field - MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER, ///< (read only) + MBG_GNSS_FLAG_EXCLUSIVE, ///< Only one of the supported GNSS systems can be used at the same time + MBG_GNSS_FLAG_HAS_PRIORITY, ///< Priority can be configured using the ::MBG_GNSS_MODE_SETTINGS::prio field + MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER, ///< The ::GNSS_SAT_INFO_IDX structure is supported by the device + MBG_GNSS_FLAG_HAS_SV_STATUS, ///< The ::GNSS_SV_STATUS_IDX structure is supported by the device + MBG_GNSS_FLAG_IS_MULTIBAND, ///< Indicates, that the receiver is a multiband receiver and therefore + ///< supports usage of any combination of GNSS types (even more than 3 types) N_MBG_GNSS_FLAGS }; /** - * @brief Flag masks used with MBG_GNSS_MODE_SETTINGS::flags and MBG_GNSS_MODE_INFO::flags + * @brief Flag masks used with ::MBG_GNSS_MODE_INFO::flags * - * @see ::MBG_GNSS_MODE_FLAG_BITS + * @see ::MBG_GNSS_MODE_INFO_FLAG_BITS */ -enum MBG_GNSS_MODE_FLAG_MASKS +enum MBG_GNSS_MODE_INFO_FLAG_MASKS { - MBG_GNSS_FLAG_MSK_EXCLUSIVE = ( 1UL << MBG_GNSS_FLAG_EXCLUSIVE ), ///< see ::MBG_GNSS_FLAG_EXCLUSIVE - MBG_GNSS_FLAG_MSK_HAS_PRIORITY = ( 1UL << MBG_GNSS_FLAG_HAS_PRIORITY ), ///< see ::MBG_GNSS_FLAG_HAS_PRIORITY - MBG_GNSS_FLAG_MSK_SAT_INFO_IDX_SUPP_SER = ( 1UL << MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER ) ///< see ::MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER + MBG_GNSS_FLAG_MSK_EXCLUSIVE = ( 1UL << MBG_GNSS_FLAG_EXCLUSIVE ), ///< See ::MBG_GNSS_FLAG_EXCLUSIVE + MBG_GNSS_FLAG_MSK_HAS_PRIORITY = ( 1UL << MBG_GNSS_FLAG_HAS_PRIORITY ), ///< See ::MBG_GNSS_FLAG_HAS_PRIORITY + MBG_GNSS_FLAG_MSK_SAT_INFO_IDX_SUPP_SER = ( 1UL << MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER ), ///< See ::MBG_GNSS_FLAG_SAT_INFO_IDX_SUPP_SER + MBG_GNSS_FLAG_MSK_HAS_SV_STATUS = ( 1UL << MBG_GNSS_FLAG_HAS_SV_STATUS ), ///< See ::MBG_GNSS_FLAG_HAS_SV_STATUS + MBG_GNSS_FLAG_MSK_IS_MULTIBAND = ( 1UL << MBG_GNSS_FLAG_IS_MULTIBAND ) ///< See ::MBG_GNSS_FLAG_IS_MULTIBAND }; - - #define MAX_USED_SATS 32 /** * @brief Satellite information for a particular GNSS type. */ -typedef struct +typedef struct gnss_sat_info_s { uint8_t gnss_type; ///< GNSS type as enumerated in ::MBG_GNSS_TYPES uint8_t reserved; ///< Reserved, currently always 0 @@ -7247,10 +11561,11 @@ typedef struct } GNSS_SAT_INFO; #define _mbg_swab_gnss_sat_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->good_svs ); \ _mbg_swab16( &(_p)->svs_in_view ); \ -} +} while ( 0 ) @@ -7261,17 +11576,231 @@ typedef struct */ typedef struct { - uint16_t idx; ///< GNSS system type index - GNSS_SAT_INFO gnss_sat_info; ///< see ::GNSS_SAT_INFO + /// @brief GNSS system type index according to ::MBG_GNSS_MODE_INFO::supp_gnss_types. + /// + /// I.e., idx 0 corresponds to the GNSS system for which the least significant + /// bit is set in ::MBG_GNSS_MODE_INFO::supp_gnss_types, idx 1 corresponds to + /// GNSS system for which the next higher bit is set, etc. + /// + /// @note This must ***not*** necessarily match the sequence + /// of the ::MBG_GNSS_TYPES enumeration. + MBG_MSG_IDX idx; + + GNSS_SAT_INFO gnss_sat_info; ///< See ::GNSS_SAT_INFO } GNSS_SAT_INFO_IDX; -#define _mbg_swab_gnss_sat_info_idx( _p ) \ -{ \ - _mbg_swab16( &(_p)->idx ); \ +#define _mbg_swab_gnss_sat_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ _mbg_swab_gnss_sat_info( &(_p)->gnss_sat_info ); \ -} +} while ( 0 ) + + + +/** + * @defgroup group_gnss_sv_status GNSS Satellite Status + * + * @note These structures and associated types are only supported by a device + * if ::MBG_GNSS_FLAG_MSK_HAS_SV_STATUS is set // ::FIXME + * + * @{ */ + +/** + * @brief Detailed GNSS satellite status + * + * @note Pure GPS receivers may only support the ::SV_INFO structure. + * + * @see ::GNSS_SV_STATUS_IDX + * @see ::SV_INFO + * @see @ref group_gnss_sv_stat_flags + */ +typedef struct gnss_sv_status_s +{ + uint8_t gnss_type; ///< GNSS type as enumerated in ::MBG_GNSS_TYPES + uint8_t svno; ///< Satellite number, see ::TODO + uint8_t cn_ratio; ///< Carrier-to-noise ratio [dbHz] + int8_t elev; ///< Elevation [deg], range: -90..90 deg + + int16_t azim; ///< Azimuth [deg], range: 0..360 deg + int16_t pr_residual; ///< Pseudo range residual [m] + + uint32_t stat_flags; ///< see @ref group_gnss_sv_stat_flags + +} GNSS_SV_STATUS; + +#define _mbg_swab_gnss_sv_status( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->gnss_type ); \ + _mbg_swab8( &(_p)->svno ); \ + _mbg_swab8( &(_p)->cn_ratio ); \ + _mbg_swab8( &(_p)->elev ); \ + _mbg_swab16( &(_p)->azim ); \ + _mbg_swab16( &(_p)->pr_residual ); \ + _mbg_swab32( &(_p)->stat_flags ); \ +} while ( 0 ) + + + +/** + * @defgroup group_gnss_sv_stat_flags GNSS status flags encoding + * + * Used with ::GNSS_SV_STATUS::stat_flags. + * + * @{ */ + +/// Bits 0 to 2 are a 3 bit quality indicator, see ::GNSS_SV_STAT_QUALITY_INDS +#define _gnss_sv_stat_quality_ind( __stat_flags ) \ + ( (uint8_t) ( (__stat_flags) & 0x00000007UL ) ) + +/// Bit 3 is set if the SV is actually used for navigation +#define _gnss_sv_stat_sv_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00000008UL ) != 0 ) + +/// Bits 4 and 5 are a 2 bit health code, see ::GNSS_SV_STAT_HEALTH_CODES +#define _gnss_sv_stat_health_code( __stat_flags ) \ + ( (uint8_t) ( ( (__stat_flags) & 0x00000030UL ) >> 4 ) ) + +/// Bit 6 is set if differential correction is available for this SV +#define _gnss_sv_stat_diff_corr( __stat_flags ) \ + ( ( (__stat_flags) & 0x00000040UL ) != 0 ) + +/// Bit 7 is set if carrier smoothed pseudorange is used for this SV +#define _gnss_sv_stat_smoothed( __stat_flags ) \ + ( ( (__stat_flags) & 0x00000080UL ) != 0 ) + +/// Bits 8 to 10 are a 3 bit code indicating the orbit source, see ::GNSS_SV_STAT_ORBIT_SOURCES +#define _gnss_sv_stat_orbit_src( __stat_flags ) \ + ( (uint8_t) ( ( (__stat_flags) & 0x00000700UL ) >> 8 ) ) + +/// Bit 11 is set if ephemeris parameters are available for this SV +#define _gnss_sv_stat_eph_avail( __stat_flags ) \ + ( ( (__stat_flags) & 0x00000800UL ) != 0 ) + +/// Bit 12 is set if almanac parameters are available for this SV +#define _gnss_sv_stat_alm_avail( __stat_flags ) \ + ( ( (__stat_flags) & 0x00001000UL ) != 0 ) +/// Bit 13 is set if AssistNow Offline data is available for this SV +#define _gnss_sv_stat_ano_avail( __stat_flags ) \ + ( ( (__stat_flags) & 0x00002000UL ) != 0 ) + +/// Bit 14 is set if AssistNow Autonomous data is available for this SV +#define _gnss_sv_stat_aop_avail( __stat_flags ) \ + ( ( (__stat_flags) & 0x00004000UL ) != 0 ) + +/// Bit 15 is reserved. + +/// Bit 16 is set if SBAS corrections have been used for this SV +#define _gnss_sv_stat_sbas_corr_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00010000UL ) != 0 ) + +/// Bit 17 is set if RTCM corrections have been used for this SV +#define _gnss_sv_stat_rtcm_corr_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00020000UL ) != 0 ) + +/// Bits 18 and 19 are reserved. + +/// Bit 20 is set if pseudorange corrections have been used for this SV +#define _gnss_sv_stat_pr_corr_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00100000UL ) != 0 ) + +/// Bit 21 is set if carrier range corrections have been used for this SV +#define _gnss_sv_stat_cr_corr_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00200000UL ) != 0 ) + +/// Bit 22 is set if range rate (doppler) corrections have been used for this SV +#define _gnss_sv_stat_do_corr_used( __stat_flags ) \ + ( ( (__stat_flags) & 0x00400000UL ) != 0 ) + +/// Bits 23 to 31 are reserved. +/// +/// However, we use the MSB (bit 31) here as a private extension +/// to indicate that the satellite can be received on two frequencies, +/// and the ionosphere correction is derived from the dual frequency +/// observation. +/// See ::_gnss_sv_stat_dual_freq +#define GNSS_SV_STAT_DUAL_FREQ_MSK 0x80000000UL + +#define _gnss_sv_stat_dual_freq( __stat_flags ) \ + ( ( (__stat_flags) & GNSS_SV_STAT_DUAL_FREQ_MSK ) != 0 ) + +/** @} defgroup group_gnss_sv_stat_flags */ + + +/** + * @brief Quality indicators used with ::GNSS_SV_STATUS::stat_flags + * + * @see ::_gnss_sv_stat_quality_ind + */ +enum GNSS_SV_STAT_QUALITY_INDS +{ + GNSS_SV_STAT_NO_SIGNAL, ///< No signal + GNSS_SV_STAT_SEARCHING, ///< Searching signal + GNSS_SV_STAT_ACQUIRED, ///< Signal acquired + GNSS_SV_STAT_UNUSABLE, ///< Signal detected but unusable + GNSS_SV_STAT_CODE_LOCKED, ///< Code locked and time synchronized + GNSS_SV_STAT_CODE_CARRIER_LOCKED, ///< Code and carrier locked, and time synchronized + GNSS_SV_STAT_CODE_CARRIER_LOCKED_2, ///< Code and carrier locked, and time synchronized + GNSS_SV_STAT_CODE_CARRIER_LOCKED_3 ///< Code and carrier locked, and time synchronized +}; + + +/** + * @brief Health indicators used with ::GNSS_SV_STATUS::stat_flags + * + * @see ::_gnss_sv_stat_health_code + */ +enum GNSS_SV_STAT_HEALTH_CODES +{ + GNSS_SV_STAT_HEALTH_UNKNOWN, ///< Health status unknown + GNSS_SV_STAT_HEALTH_OK, ///< Healthy + GNSS_SV_STAT_HEALTH_NOT_OK ///< Unhealthy +}; + + +/** + * @brief Orbit source codes used with ::GNSS_SV_STATUS::stat_flags + * + * @see ::_gnss_sv_stat_orbit_src + */ +enum GNSS_SV_STAT_ORBIT_SOURCES +{ + GNSS_SV_STAT_ORBIT_SRC_UNKNOWN, ///< Orbit source unknown + GNSS_SV_STAT_ORBIT_SRC_EPH, ///< Ephemeris data used for orbit + GNSS_SV_STAT_ORBIT_SRC_ALM, ///< Almanac data used for orbit + GNSS_SV_STAT_ORBIT_SRC_ASSN_OFFL, ///< AssistNow Offline orbit is used + GNSS_SV_STAT_ORBIT_SRC_ASSN_AUTO, ///< AssistNow Autonomous orbit is used + GNSS_SV_STAT_ORBIT_OTHER_1, ///< Other orbit information is used + GNSS_SV_STAT_ORBIT_OTHER_2, ///< Other orbit information is used + GNSS_SV_STAT_ORBIT_OTHER_3 ///< Other orbit information is used +}; + + + +/** + * @brief Detailed GNSS satellite status, plus index + * + * @see ::GNSS_SV_STATUS + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; ///< Range 0..::MBG_GNSS_MODE_INFO::n_sv_status-1 + GNSS_SV_STATUS gnss_sv_status; + +} GNSS_SV_STATUS_IDX; + +#define _mbg_swab_gnss_sv_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_gnss_sv_status( &(_p)->gnss_sv_status ); \ +} while ( 0 ) + + +/** @} defgroup group_gnss_sv_status */ @@ -7288,11 +11817,14 @@ typedef struct #endif #define _mbg_swab_ident( _p ) \ +do \ { \ int i; \ for ( i = 0; i < 4; i++ ) \ _mbg_swab32( &(_p)->lw[i] ); \ -} +} while ( 0 ) + + /** * @brief A data type used to configure the length of an antenna cable [m] @@ -7316,12 +11848,15 @@ typedef uint16_t ANT_CABLE_LEN; /** * @brief The MAC address of a network interface */ -typedef struct +typedef struct mbg_mac_addr_s { uint8_t b[6]; } MBG_MAC_ADDR; +#define _mbg_swab_mbg_mac_addr( _p ) \ + _nop_macro_fnc() + /** @@ -7330,7 +11865,7 @@ typedef struct typedef uint32_t IP4_ADDR; #define _mbg_swab_ip4_addr( _p ) \ - _mbg_swab32( _p ); + _mbg_swab32( _p ) @@ -7345,10 +11880,25 @@ typedef uint32_t IP4_ADDR; */ typedef struct { - uint8_t b[IP6_ADDR_BYTES]; ///< bytes holding the address bits, b[0] == LSBs + uint8_t b[IP6_ADDR_BYTES]; ///< bytes holding the address bits (not the string notation), b[0] == LSBs } IP6_ADDR; +#define _mbg_swab_ip6_addr( _p ) _nop_macro_fnc() + + + +/** + * @brief An IPv6 address plus number of netmask bits + */ +typedef struct +{ + IP6_ADDR addr; ///< bit mask of the bytes holding the address bits, b[0] == LSBs + uint8_t prefix; ///< Number of subnet mask bits for CIDR notation, e.g. 24 for /24 + uint8_t reserved[3]; ///< Reserved, alignment, currently 0 + +} IP6_ADDR_CIDR; + /** @brief The max number of chars required for an IPv6 address string */ @@ -7361,20 +11911,96 @@ typedef struct typedef char IP6_ADDR_STR[IP6_ADDR_STR_SIZE]; + +/** + * @brief Possible IPv6 Multicast Scopes + * + * If the first (most significant) byte of an IPv6 address is 0xFF this + * indicates that the address is a multicast address, and in this case + * the second byte determines the scope for which the specified address + * is valid. These scope ID numbers are assigned in RFC 7346 which + * supersedes RFC 4291. + * + * @see ::IPV6_MULTICAST_SCOPE_NAME_TABLE_ENTRIES + */ +enum IPV6_MULTICAST_SCOPES +{ + IPV6_MULTICAST_SCOPE_INTF_LOCAL = 0x01, ///< Interface-Local scope + IPV6_MULTICAST_SCOPE_LINK_LOCAL, ///< Link-Local scope + IPV6_MULTICAST_SCOPE_REALM_LOCAL, ///< Realm-Local scope + IPV6_MULTICAST_SCOPE_ADMIN_LOCAL, ///< Admin-Local scope + IPV6_MULTICAST_SCOPE_SITE_LOCAL, ///< Site-Local scope + IPV6_MULTICAST_SCOPE_ORGA_LOCAL = 0x08, ///< Organization-Local scope + IPV6_MULTICAST_SCOPE_GLOBAL_SCOPE = 0x0E ///< Global scope +}; + + /** - * @brief A host's fully qualified domain name (FQDN), or a numeric IP address string + * @brief Name strings for IPv6 multicast scopes + * + * This can e.g. be used to initialize an array of ::MBG_CODE_NAME_TABLE_ENTRY elements. + * + * @see ::IPV6_MULTICAST_SCOPES + */ +#define IPV6_MULTICAST_SCOPE_NAME_TABLE_ENTRIES \ +{ \ + { IPV6_MULTICAST_SCOPE_INTF_LOCAL, "FF01 - Interface-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_LINK_LOCAL, "FF02 - Link-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_REALM_LOCAL, "FF03 - Realm-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_ADMIN_LOCAL, "FF04 - Admin-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_SITE_LOCAL, "FF05 - Site-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_ORGA_LOCAL, "FF08 - Organization-Local Scope" }, \ + { IPV6_MULTICAST_SCOPE_GLOBAL_SCOPE, "FF0E - Global Scope" }, \ + { 0, NULL } \ +} + + + +/** + * @brief The maximum length of a fully qualified host/domain domain name (FQDN) * * In theory each single component (host name, domain name, top level domain name) * of a FQDN can have up to 63 characters, but the overall length is limited to - * 255 characters. We specify one more character for the trailing 0. + * 255 characters (see RFC-1123). We specify one more character for the trailing 0. */ -typedef char MBG_HOSTNAME[256]; ///< ASCIIZ format +#define MBG_MAX_HOSTNAME_LEN 256 + + +/** + * @brief A buffer for a fully qualified domain name (FQDN) or a numeric IP address string + */ +typedef char MBG_HOSTNAME[MBG_MAX_HOSTNAME_LEN]; ///< ASCIIZ format + +#define _mbg_swab_mbg_host_name( _p ) _nop_macro_fnc() + /** @} defgroup group_net_basic_types */ /** + * @brief The maximum length of an interface name + * + * We use an extra name here for the Meinberg-specific structures + * to avoid a name clash with system definitions, e.g. Linux systems + * define IFNAMSIZ usually as 16 in linux/if.h. + */ +#define MBG_IFNAMSIZ 16 + + +/** + * @brief Hardware type for identification of physical interfaces + * + */ +enum MBG_NET_HW_TYPES +{ + MBG_NET_HW_TYPE_UNKNOWN, + MBG_ARPHRD_ETHER, + N_MBG_NET_HW_TYPES +}; + + +/** * @defgroup group_vlan_cfg Definitions used with VLAN configuration * * @{ */ @@ -7386,7 +12012,7 @@ typedef char MBG_HOSTNAME[256]; ///< ASCIIZ format */ typedef uint16_t MBG_VLAN_CFG; -#define _mbg_swab_mbg_vlan_cfg( _p ) _mbg_swab16( _p ); +#define _mbg_swab_mbg_vlan_cfg( _p ) _mbg_swab16( _p ) #define VLAN_ID_BITS 12 ///< number of bits to hold the ID #define N_VLAN_ID ( 1 << VLAN_ID_BITS ) ///< number of ID values @@ -7436,12 +12062,13 @@ typedef struct IP4_ADDR netmask; ///< the network mask IP4_ADDR broad_addr; ///< the broadcast address IP4_ADDR gateway; ///< the default gateway - uint16_t flags; ///< see ::MBG_IP4_FLAG_MASKS + uint16_t flags; ///< See ::MBG_IP4_FLAG_MASKS MBG_VLAN_CFG vlan_cfg; ///< VLAN configuration } IP4_SETTINGS; #define _mbg_swab_ip4_settings( _p ) \ +do \ { \ _mbg_swab_ip4_addr( &(_p)->ip_addr ); \ _mbg_swab_ip4_addr( &(_p)->netmask ); \ @@ -7449,15 +12076,15 @@ typedef struct _mbg_swab_ip4_addr( &(_p)->gateway ); \ _mbg_swab16( &(_p)->flags ); \ _mbg_swab_mbg_vlan_cfg( &(_p)->vlan_cfg ); \ -} +} while ( 0 ) /** * @brief Simple LAN interface information * - * This structure can be retrieved from a device - * to check the device's capabilities. + * This structure can be obtained from a device + * to check the capabilities of the device. * * It is only supported if the flag ::GPS_HAS_LAN_IP4 is set * in ::RECEIVER_INFO::features. @@ -7472,19 +12099,20 @@ typedef struct char ver_str[GPS_ID_STR_SIZE]; ///< version string char sernum[GPS_ID_STR_SIZE]; ///< serial number uint32_t rsvd_0; ///< reserved, currently always 0 - uint16_t flags; ///< see ::MBG_IP4_FLAG_MASKS + uint16_t flags; ///< See ::MBG_IP4_FLAG_MASKS uint16_t rsvd_1; ///< reserved, currently always 0 } LAN_IF_INFO; #define _mbg_swab_lan_if_info( _p ) \ +do \ { \ _mbg_swab16( &(_p)->type ); \ _mbg_swab16( &(_p)->ver_code ); \ _mbg_swab32( &(_p)->rsvd_0 ); \ _mbg_swab16( &(_p)->flags ); \ _mbg_swab16( &(_p)->rsvd_1 ); \ -} +} while ( 0 ) /** @@ -7506,10 +12134,20 @@ enum LAN_IF_TYPES */ enum MBG_IP4_FLAG_BITS { - IP4_BIT_DHCP, ///< DHCP supported (::LAN_IF_INFO) / enabled (::IP4_SETTINGS) - IP4_BIT_LINK, ///< only used in ::IP4_SETTINGS to report link state - IP4_BIT_VLAN, ///< VLAN supported (::LAN_IF_INFO) / enabled (::IP4_SETTINGS) - N_IP4_BIT ///< number of defined flag bits + /// In ::LAN_IF_INFO::flags this reports if DHCP is supported by the device. + /// If supported then it can also be used with ::IP4_SETTINGS::flags to enable + /// or disable DHCP for the network interface. + IP4_BIT_DHCP, + + /// Only used with ::IP4_SETTINGS::flags. Set if port link has been established. + IP4_BIT_LINK, + + /// In ::LAN_IF_INFO::flags this reports if VLAN is supported by the device. + /// If supported then it can also be used with ::IP4_SETTINGS::flags to enable + /// or disable VLAN for the network interface. + IP4_BIT_VLAN, + + N_IP4_BIT ///< number of defined flag bits }; @@ -7520,9 +12158,9 @@ enum MBG_IP4_FLAG_BITS */ enum MBG_IP4_FLAG_MASKS { - IP4_MSK_DHCP = ( 1UL << IP4_BIT_DHCP ), ///< see ::IP4_BIT_DHCP - IP4_MSK_LINK = ( 1UL << IP4_BIT_LINK ), ///< see ::IP4_BIT_LINK - IP4_MSK_VLAN = ( 1UL << IP4_BIT_VLAN ), ///< see ::IP4_BIT_VLAN + IP4_MSK_DHCP = ( 1UL << IP4_BIT_DHCP ), ///< See ::IP4_BIT_DHCP + IP4_MSK_LINK = ( 1UL << IP4_BIT_LINK ), ///< See ::IP4_BIT_LINK + IP4_MSK_VLAN = ( 1UL << IP4_BIT_VLAN ), ///< See ::IP4_BIT_VLAN }; /** @} defgroup group_ip4_cfg */ @@ -7541,7 +12179,8 @@ enum MBG_IP_ADDR_TYPES { MBG_IP_ADDR_TYPE_UNKNOWN, MBG_IP_ADDR_TYPE_IP4, - MBG_IP_ADDR_TYPE_IP6 + MBG_IP_ADDR_TYPE_IP6, + N_MBG_IP_ADDR_TYPES }; /* @@ -7561,83 +12200,205 @@ enum MBG_IP_ADDR_TYPES /** - * @brief Network link speed modes + * @brief Feature flag bits used to define ::MBG_NET_GLB_CFG_INFO_MASKS + * + * @see ::MBG_NET_GLB_CFG_INFO_MASKS + */ +enum MBG_NET_GLB_CFG_INFO_FLAGS +{ + MBG_NET_GLB_SUPP_STAGE_2, ///< Supports commands which have been added in stage 2 + MBG_NET_GLB_SUPP_BONDING, ///< Supports bonding + MBG_NET_GLB_SUPP_ADD_CONF, ///< Supports additional network configuration (i.e. via script) + MBG_NET_GLB_SUPP_EXT_ROUTING, ///< Supports extended routing (multiple default gateways, routing tables) + N_MBG_NET_GLB_INFO_FLAGS +}; + + +/** + * @brief Flag masks used with ::MBG_NET_GLB_CFG_INFO::feat_flags * - * @see ::MBG_NET_LINK_MODE_MASKS + * @see ::MBG_NET_GLB_CFG_INFO_FLAGS + */ +enum MBG_NET_GLB_CFG_INFO_MASKS +{ + MBG_NET_GLB_SUPP_STAGE_2_MASK = (1UL << MBG_NET_GLB_SUPP_STAGE_2), ///< See ::MBG_NET_GLB_SUPP_STAGE_2 + MBG_NET_GLB_SUPP_BONDING_MASK = (1UL << MBG_NET_GLB_SUPP_BONDING), ///< See ::MBG_NET_GLB_SUPP_BONDING + MBG_NET_GLB_SUPP_ADD_CONF_MASK = (1UL << MBG_NET_GLB_SUPP_ADD_CONF), ///< See ::MBG_NET_GLB_SUPP_ADD_CONF + MBG_NET_GLB_SUPP_EXT_ROUTING_MASK = (1UL << MBG_NET_GLB_SUPP_EXT_ROUTING) ///< See ::MBG_NET_GLB_SUPP_EXT_ROUTING +}; + + + +/** + * @brief Network interface link speed mode enumeration * - * Note: Half duplex is not supported for 10GBit + * @see @ref MBG_NET_INTF_LINK_SPEED_MODE_MASKS */ -enum MBG_NET_LINK_MODES +enum MBG_NET_INTF_LINK_SPEED_MODES { - MBG_NET_LINK_MODE_AUTONEG, ///< auto negotiation - MBG_NET_LINK_MODE_10_BT_H, ///< 10 MBit half duplex - MBG_NET_LINK_MODE_10_BT_F, ///< 10 MBit full duplex - MBG_NET_LINK_MODE_100_BT_H, ///< 100 MBit half duplex - MBG_NET_LINK_MODE_100_BT_F, ///< 100 MBit full duplex - MBG_NET_LINK_MODE_1000_BT_H, ///< 1 GBit half duplex - MBG_NET_LINK_MODE_1000_BT_F, ///< 1 GBit full duplex - MBG_NET_LINK_MODE_10000_BT_F, ///< 10 GBit Full Duplex - N_MBG_NET_LINK_MODES + MBG_NET_INTF_LINK_SPEED_MODE_UNKNOWN, ///< Unknown speed mode + MBG_NET_INTF_LINK_SPEED_MODE_10_T_HALF, ///< 10baseT Half Duplex (10 MBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_10_T_FULL, ///< 10baseT Full Duplex (10 MBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_100_T_HALF, ///< 100baseT Half Duplex (100 MBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_100_T_FULL, ///< 100baseT Full Duplex (100 MBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_1000_T_HALF, ///< 1000baseT Half Duplex (1 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_1000_T_FULL, ///< 1000baseT Full Duplex (1 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_1000_KX_FULL, ///< 1000baseKX Full Duplex (1 GBit/s) + + MBG_NET_INTF_LINK_SPEED_MODE_2500_X_FULL, ///< 2500baseX Full Duplex (2.5 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_10000_T_FULL, ///< 10000baseT Full Duplex (10 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_10000_KX4_FULL, ///< 10000baseKX4 Full Duplex (10 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_10000_KR_FULL, ///< 10000baseKR Full Duplex (10 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_10000_R_FEC, ///< 10000baseR FEC (forward error correction) (10 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_20000_MLD2_FULL, ///< 20000baseMLD2 Full Duplex (20 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_20000_KR2_FULL, ///< 20000baseKR2 Full Duplex (20 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_40000_KR4_FULL, ///< 40000baseKR4 Full Duplex (40 GBit/s) + + MBG_NET_INTF_LINK_SPEED_MODE_40000_CR4_FULL, ///< 40000baseCR4 Full Duplex (40 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_40000_SR4_FULL, ///< 40000baseSR4 Full Duplex (40 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_40000_LR4_FULL, ///< 40000baseLR4 Full Duplex (40 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_56000_KR4_FULL, ///< 56000baseKR4 Full Duplex (56 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_56000_CR4_FULL, ///< 56000baseCR4 Full Duplex (56 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_56000_SR4_FULL, ///< 56000baseSR4 Full Duplex (56 GBit/s) + MBG_NET_INTF_LINK_SPEED_MODE_56000_LR4_FULL, ///< 56000baseLR4 Full Duplex (56 GBit/s) + + N_MBG_NET_INTF_LINK_SPEED_MODES }; + +/** + * @brief Network interface link speed mode masks + * + * @see ::MBG_NET_INTF_LINK_SPEED_MODES + * + * @anchor MBG_NET_INTF_LINK_SPEED_MODE_MASKS @{ */ + +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_UNKNOWN ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_UNKNOWN ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_UNKNOWN +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_HALF ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10_T_HALF ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10_T_HALF +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10_T_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10_T_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_HALF ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_100_T_HALF ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_100_T_HALF +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_100_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_100_T_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_100_T_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_1000_T_HALF ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_1000_T_HALF ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_1000_T_HALF +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_1000_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_1000_T_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_1000_T_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_1000_KX_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_1000_KX_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_1000_KX_FULL + +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_2500_X_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_2500_X_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_2500_X_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_T_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_T_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10000_T_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_KX4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_KX4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10000_KX4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_KR_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_KR_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10000_KR_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_10000_R_FEC ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_10000_R_FEC ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_10000_R_FEC +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_20000_MLD2_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_20000_MLD2_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_20000_MLD2_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_20000_KR2_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_20000_KR2_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_20000_KR2_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_KR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_KR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_40000_KR4_FULL + +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_CR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_CR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_40000_CR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_SR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_SR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_40000_SR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_40000_LR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_40000_LR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_40000_LR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_KR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_KR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_56000_KR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_CR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_CR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_56000_CR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_SR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_SR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_56000_SR4_FULL +#define MBG_NET_INTF_LINK_SPEED_MODE_MASK_56000_LR4_FULL ( 1UL << MBG_NET_INTF_LINK_SPEED_MODE_56000_LR4_FULL ) ///< See ::MBG_NET_INTF_LINK_SPEED_MODE_56000_LR4_FULL + +/** @} anchor MBG_NET_INTF_LINK_SPEED_MODE_MASKS */ + + + /** - * @brief Network link speed mode masks + * @brief Network interface link speeds [Mb/s] * - * @see ::MBG_NET_LINK_MODES + * @see @ref MBG_NET_INTF_LINK_SPEED_MODE_MASKS */ -enum MBG_NET_LINK_MODE_MASKS +enum MBG_NET_INTF_LINK_SPEEDS { - MBG_NET_LINK_MODE_MASK_AUTONEG = ( 1UL << MBG_NET_LINK_MODE_AUTONEG ), ///< see ::MBG_NET_LINK_MODE_AUTONEG - MBG_NET_LINK_MODE_MASK_10_BT_H = ( 1UL << MBG_NET_LINK_MODE_10_BT_H ), ///< see ::MBG_NET_LINK_MODE_10_BT_H - MBG_NET_LINK_MODE_MASK_10_BT_F = ( 1UL << MBG_NET_LINK_MODE_10_BT_F ), ///< see ::MBG_NET_LINK_MODE_10_BT_F - MBG_NET_LINK_MODE_MASK_100_BT_H = ( 1UL << MBG_NET_LINK_MODE_100_BT_H ), ///< see ::MBG_NET_LINK_MODE_100_BT_H - MBG_NET_LINK_MODE_MASK_100_BT_F = ( 1UL << MBG_NET_LINK_MODE_100_BT_F ), ///< see ::MBG_NET_LINK_MODE_100_BT_F - MBG_NET_LINK_MODE_MASK_1000_BT_H = ( 1UL << MBG_NET_LINK_MODE_1000_BT_H ), ///< see ::MBG_NET_LINK_MODE_1000_BT_H - MBG_NET_LINK_MODE_MASK_1000_BT_F = ( 1UL << MBG_NET_LINK_MODE_1000_BT_F ), ///< see ::MBG_NET_LINK_MODE_1000_BT_F - MBG_NET_LINK_MODE_MASK_10000_BT_F = ( 1UL << MBG_NET_LINK_MODE_10000_BT_F ) ///< see ::MBG_NET_LINK_MODE_10000_BT_F + MBG_NET_INTF_LINK_SPEED_UNKNOWN = 0UL, + MBG_NET_INTF_LINK_SPEED_10 = 10UL, + MBG_NET_INTF_LINK_SPEED_100 = 100UL, + MBG_NET_INTF_LINK_SPEED_1000 = 1000UL, + MBG_NET_INTF_LINK_SPEED_2500 = 2500UL, + MBG_NET_INTF_LINK_SPEED_10000 = 10000UL, + MBG_NET_INTF_LINK_SPEED_20000 = 20000UL, + MBG_NET_INTF_LINK_SPEED_40000 = 40000UL, + MBG_NET_INTF_LINK_SPEED_56000 = 56000UL }; /** - * @brief Network link port types + * @brief Network interface link port types * - * @see ::MBG_NET_LINK_PORT_MASKS + * @see ::MBG_NET_INTF_LINK_PORT_TYPE_MASKS */ -enum MBG_NET_LINK_PORTS +enum MBG_NET_INTF_LINK_PORT_TYPES { - MBG_NET_LINK_PORT_AUTO, ///< auto detection - MBG_NET_LINK_PORT_TP, ///< Twisted Pair (TP) - MBG_NET_LINK_PORT_AUI, ///< Attachment Unit Interface (AUI), externel transceiver - MBG_NET_LINK_PORT_MII, ///< Media Independent Interface (MII), external receiver - MBG_NET_LINK_PORT_FIBRE, ///< fibre optic - MBG_NET_LINK_PORT_BNC, ///< coaxial cable - N_MBG_NET_LINK_PORTS + MBG_NET_INTF_LINK_PORT_TYPE_UNKNOWN, ///< Unknown port type + MBG_NET_INTF_LINK_PORT_TYPE_TP, ///< Twisted Pair (TP) copper cable + MBG_NET_INTF_LINK_PORT_TYPE_FIBRE, ///< Fibre Optic (FO) cable + MBG_NET_INTF_LINK_PORT_TYPE_BNC, ///< Coaxial BNC cable + MBG_NET_INTF_LINK_PORT_TYPE_AUI, ///< Attachment Unit Interface (AUI), externel transceiver + MBG_NET_INTF_LINK_PORT_TYPE_MII, ///< Media Independent Interface (MII), external receiver + MBG_NET_INTF_LINK_PORT_TYPE_DA, ///< Direct attach SFP+ connection + N_MBG_NET_INTF_LINK_PORT_TYPES }; + /** - * @brief Network link port type masks + * @brief Network interface link port masks * - * @see ::MBG_NET_LINK_PORTS + * @see ::MBG_NET_INTF_LINK_PORT_TYPES */ -enum MBG_NET_LINK_PORT_MASKS +enum MBG_NET_INTF_LINK_PORT_TYPE_MASKS { - MBG_NET_LINK_PORT_MASK_AUTO = ( 1UL << MBG_NET_LINK_PORT_AUTO ), ///< see ::MBG_NET_LINK_PORT_AUTO - MBG_NET_LINK_PORT_MASK_TP = ( 1UL << MBG_NET_LINK_PORT_TP ), ///< see ::MBG_NET_LINK_PORT_TP - MBG_NET_LINK_PORT_MASK_AUI = ( 1UL << MBG_NET_LINK_PORT_AUI ), ///< see ::MBG_NET_LINK_PORT_AUI - MBG_NET_LINK_PORT_MASK_MII = ( 1UL << MBG_NET_LINK_PORT_MII ), ///< see ::MBG_NET_LINK_PORT_MII - MBG_NET_LINK_PORT_MASK_FIBRE = ( 1UL << MBG_NET_LINK_PORT_FIBRE ), ///< see ::MBG_NET_LINK_PORT_FIBRE - MBG_NET_LINK_PORT_MASK_BNC = ( 1UL << MBG_NET_LINK_PORT_BNC ) ///< see ::MBG_NET_LINK_PORT_BNC + MBG_NET_INTF_LINK_PORT_TYPE_MASK_UNKNOWN = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_UNKNOWN ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_UNKNOWN + MBG_NET_INTF_LINK_PORT_TYPE_MASK_TP = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_TP ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_TP + MBG_NET_INTF_LINK_PORT_TYPE_MASK_FIBRE = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_FIBRE ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_FIBRE + MBG_NET_INTF_LINK_PORT_TYPE_MASK_BNC = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_BNC ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_BNC + MBG_NET_INTF_LINK_PORT_TYPE_MASK_AUI = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_AUI ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_AUI + MBG_NET_INTF_LINK_PORT_TYPE_MASK_MII = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_MII ), ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_MII + MBG_NET_INTF_LINK_PORT_TYPE_MASK_DA = ( 1UL << MBG_NET_INTF_LINK_PORT_TYPE_DA ) ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_DA }; /** - * @brief Network link state bits + * @brief Initializers for network interface link port type long strings + * + * @see ::MBG_NET_INTF_LINK_PORT_TYPES + */ +#define MBG_NET_INTF_LINK_PORT_TYPE_LONG_STRS \ +{ \ + "Unknown", \ + "Twisted Pair", \ + "Fibre Optic", \ + "Coaxial BNC", \ + "Attachment Unit Interface", \ + "Media Independent Interface", \ + "Direct Attach SFP+" \ +} + + +/** + * @brief Initializers for network interface link port type short strings + * + * @see ::MBG_NET_INTF_LINK_PORT_TYPES + */ +#define MBG_NET_INTF_LINK_PORT_TYPE_SHORT_STRS \ +{ \ + "Unknown", \ + "TP", \ + "FO", \ + "BNC", \ + "AUI", \ + "MII", \ + "DA" \ +} + + +/** + * @brief Network interface link state bits * - * @see ::MBG_NET_LINK_STATE_MASKS + * @see @ref MBG_NET_INTF_LINK_STATE_MASKS * * @note See official Linux kernel documentation * https://www.kernel.org/doc/Documentation/networking/operstates.txt @@ -7645,199 +12406,249 @@ enum MBG_NET_LINK_PORT_MASKS * using similar names struct IP_ADAPTER_ADDRESSES which is explained at * http://msdn.microsoft.com/en-us/library/windows/desktop/aa366058%28v=vs.85%29.aspx */ -enum MBG_NET_LINK_STATE_BITS -{ - MBG_NET_LINK_STATE_BIT_UP, - MBG_NET_LINK_STATE_BIT_BROADCAST, - MBG_NET_LINK_STATE_BIT_LOOPBACK, - MBG_NET_LINK_STATE_BIT_P2P, - MBG_NET_LINK_STATE_BIT_RUNNING, - MBG_NET_LINK_STATE_BIT_NO_ARP, - MBG_NET_LINK_STATE_BIT_PROMISC, - MBG_NET_LINK_STATE_BIT_MASTER, - MBG_NET_LINK_STATE_BIT_SLAVE, - MBG_NET_LINK_STATE_BIT_MULTICAST, - MBG_NET_LINK_STATE_BIT_LOWER_UP, - MBG_NET_LINK_STATE_BIT_DORMANT, - MBG_NET_LINK_STATE_BIT_ECHO, - N_MBG_NET_LINK_STATE_BITS +enum MBG_NET_INTF_LINK_STATE_BITS +{ + MBG_NET_INTF_LINK_STATE_BIT_UP, + MBG_NET_INTF_LINK_STATE_BIT_RUNNING, + MBG_NET_INTF_LINK_STATE_BIT_LOWER_UP, + MBG_NET_INTF_LINK_STATE_BIT_DORMANT, + MBG_NET_INTF_LINK_STATE_BIT_BROADCAST, + MBG_NET_INTF_LINK_STATE_BIT_MULTICAST, + MBG_NET_INTF_LINK_STATE_BIT_ALL_MULTI, + MBG_NET_INTF_LINK_STATE_BIT_DEBUG, + + MBG_NET_INTF_LINK_STATE_BIT_LOOPBACK, + MBG_NET_INTF_LINK_STATE_BIT_POINT_TO_POINT, + MBG_NET_INTF_LINK_STATE_BIT_NO_ARP, + MBG_NET_INTF_LINK_STATE_BIT_PROMISC, + MBG_NET_INTF_LINK_STATE_BIT_MASTER, + MBG_NET_INTF_LINK_STATE_BIT_SLAVE, + MBG_NET_INTF_LINK_STATE_BIT_PORT_SEL, + MBG_NET_INTF_LINK_STATE_BIT_AUTO_MEDIA, + + MBG_NET_INTF_LINK_STATE_BIT_ECHO, + MBG_NET_INTF_LINK_STATE_BIT_DYNAMIC, + MBG_NET_INTF_LINK_STATE_BIT_NO_TRAILERS, + + N_MBG_NET_INTF_LINK_STATE_BITS }; + /** - * @brief Network link state masks + * @brief Network interface link state masks * - * @see ::MBG_NET_LINK_STATE_BITS (reclined to Linux' if.h, Windows is similiar) - */ -enum MBG_NET_LINK_STATE_MASKS -{ - MBG_NET_LINK_STATE_MASK_UP = ( 1UL << MBG_NET_LINK_STATE_BIT_UP ), ///< see ::MBG_NET_LINK_STATE_BIT_UP - MBG_NET_LINK_STATE_MASK_BROADCAST = ( 1UL << MBG_NET_LINK_STATE_BIT_BROADCAST ), ///< see ::MBG_NET_LINK_STATE_BIT_BROADCAST - MBG_NET_LINK_STATE_MASK_LOOPBACK = ( 1UL << MBG_NET_LINK_STATE_BIT_LOOPBACK ), ///< see ::MBG_NET_LINK_STATE_BIT_LOOPBACK - MBG_NET_LINK_STATE_MASK_P2P = ( 1UL << MBG_NET_LINK_STATE_BIT_P2P ), ///< see ::MBG_NET_LINK_STATE_BIT_P2P - MBG_NET_LINK_STATE_MASK_RUNNING = ( 1UL << MBG_NET_LINK_STATE_BIT_RUNNING ), ///< see ::MBG_NET_LINK_STATE_BIT_RUNNING - MBG_NET_LINK_STATE_MASK_NO_ARP = ( 1UL << MBG_NET_LINK_STATE_BIT_NO_ARP ), ///< see ::MBG_NET_LINK_STATE_BIT_NO_ARP - MBG_NET_LINK_STATE_MASK_PROMISC = ( 1UL << MBG_NET_LINK_STATE_BIT_PROMISC ), ///< see ::MBG_NET_LINK_STATE_BIT_PROMISC - MBG_NET_LINK_STATE_MASK_MASTER = ( 1UL << MBG_NET_LINK_STATE_BIT_MASTER ), ///< see ::MBG_NET_LINK_STATE_BIT_MASTER - MBG_NET_LINK_STATE_MASK_SLAVE = ( 1UL << MBG_NET_LINK_STATE_BIT_SLAVE ), ///< see ::MBG_NET_LINK_STATE_BIT_SLAVE - MBG_NET_LINK_STATE_MASK_MULTICAST = ( 1UL << MBG_NET_LINK_STATE_BIT_MULTICAST ), ///< see ::MBG_NET_LINK_STATE_BIT_MULTICAST - MBG_NET_LINK_STATE_MASK_LOWER_UP = ( 1UL << MBG_NET_LINK_STATE_BIT_LOWER_UP ), ///< see ::MBG_NET_LINK_STATE_BIT_LOWER_UP - MBG_NET_LINK_STATE_MASK_DORMANT = ( 1UL << MBG_NET_LINK_STATE_BIT_DORMANT ), ///< see ::MBG_NET_LINK_STATE_BIT_DORMANT - MBG_NET_LINK_STATE_MASK_ECHO = ( 1UL << MBG_NET_LINK_STATE_BIT_ECHO ) ///< see ::MBG_NET_LINK_STATE_BIT_ECHO -}; + * @see ::MBG_NET_INTF_LINK_STATE_BITS (reclined to Linux' if.h, Windows is similiar) + * + * @anchor MBG_NET_INTF_LINK_STATE_MASKS @{ */ + +#define MBG_NET_INTF_LINK_STATE_MASK_UP ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_UP ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_UP +#define MBG_NET_INTF_LINK_STATE_MASK_RUNNING ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_RUNNING ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_RUNNING +#define MBG_NET_INTF_LINK_STATE_MASK_LOWER_UP ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_LOWER_UP ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_LOWER_UP +#define MBG_NET_INTF_LINK_STATE_MASK_DORMANT ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_DORMANT ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_DORMANT +#define MBG_NET_INTF_LINK_STATE_MASK_BROADCAST ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_BROADCAST ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_BROADCAST +#define MBG_NET_INTF_LINK_STATE_MASK_MULTICAST ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_MULTICAST ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_MULTICAST +#define MBG_NET_INTF_LINK_STATE_MASK_ALL_MULTI ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_ALL_MULTI ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_ALL_MULTI +#define MBG_NET_INTF_LINK_STATE_MASK_DEBUG ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_DEBUG ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_DEBUG + +#define MBG_NET_INTF_LINK_STATE_MASK_LOOPBACK ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_LOOPBACK ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_LOOPBACK +#define MBG_NET_INTF_LINK_STATE_MASK_POINT_TO_POINT ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_POINT_TO_POINT ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_POINT_TO_POINT +#define MBG_NET_INTF_LINK_STATE_MASK_NO_ARP ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_NO_ARP ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_NO_ARP +#define MBG_NET_INTF_LINK_STATE_MASK_PROMISC ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_PROMISC ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_PROMISC +#define MBG_NET_INTF_LINK_STATE_MASK_MASTER ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_MASTER ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_MASTER +#define MBG_NET_INTF_LINK_STATE_MASK_SLAVE ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_SLAVE ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_SLAVE +#define MBG_NET_INTF_LINK_STATE_MASK_PORT_SEL ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_PORT_SEL ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_PORT_SEL +#define MBG_NET_INTF_LINK_STATE_MASK_AUTO_MEDIA ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_AUTO_MEDIA ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_AUTO_MEDIA + +#define MBG_NET_INTF_LINK_STATE_MASK_ECHO ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_ECHO ) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_ECHO +#define MBG_NET_INTF_LINK_STATE_MASK_DYNAMIC ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_DYNAMIC) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_DYNAMIC +#define MBG_NET_INTF_LINK_STATE_MASK_NO_TRAILERS ( 1UL << MBG_NET_INTF_LINK_STATE_BIT_NO_TRAILERS) ///< See ::MBG_NET_INTF_LINK_STATE_BIT_NO_TRAILERS + +/** @} anchor MBG_NET_INTF_LINK_STATE_MASKS */ /** - * @brief Network link option bits + * @brief Network interface link option bits * - * @see ::MBG_NET_LINK_OPT_MASKS + * @see ::MBG_NET_INTF_LINK_OPT_MASKS */ -enum MBG_NET_LINK_OPTS +enum MBG_NET_INTF_LINK_OPTS { - MBG_NET_LINK_OPT_CAN_SET_MAC, - MBG_NET_LINK_OPT_CAN_BOND, - N_MBG_NET_LINK_OPTS + MBG_NET_INTF_LINK_OPT_CAN_SET_MAC, + MBG_NET_INTF_LINK_OPT_CAN_SYNCE_IN, + MBG_NET_INTF_LINK_OPT_CAN_SYNCE_OUT, + MBG_NET_INTF_LINK_OPT_CAN_AUTONEG, + MBG_NET_INTF_LINK_OPT_CAN_NTP_HW_TS, + MBG_NET_INTF_LINK_OPT_CAN_PTP_HW_TS, + MBG_NET_INTF_LINK_OPT_HAS_NTP_LIC, ///< Indicates, that the physical interface has a license for number of NTP clients + MBG_NET_INTF_LINK_OPT_HAS_PTP_LIC, ///< Indicates, that the physical interface has a license for number of PTP clients + MBG_NET_INTF_LINK_OPT_HAS_SYNCE_STATUS, + N_MBG_NET_INTF_LINK_OPTS }; + /** - * @brief Network link option masks + * @brief Network interface link option masks * - * @see ::MBG_NET_LINK_OPTS + * @see ::MBG_NET_INTF_LINK_OPTS */ -enum MBG_NET_LINK_OPT_MASKS +enum MBG_NET_INTF_LINK_OPT_MASKS { - MBG_NET_LINK_OPT_MASK_CAN_SET_MAC = ( 1UL << MBG_NET_LINK_OPT_CAN_SET_MAC ), ///< see ::MBG_NET_LINK_OPT_CAN_SET_MAC - MBG_NET_LINK_OPT_MASK_CAN_BOND = ( 1UL << MBG_NET_LINK_OPT_CAN_BOND ) ///< see ::MBG_NET_LINK_OPT_CAN_BOND + MBG_NET_INTF_LINK_OPT_MASK_CAN_SET_MAC = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_SET_MAC ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_SET_MAC + MBG_NET_INTF_LINK_OPT_MASK_CAN_SYNCE_IN = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_SYNCE_IN ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_SYNCE_IN + MBG_NET_INTF_LINK_OPT_MASK_CAN_SYNCE_OUT = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_SYNCE_OUT ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_SYNCE_OUT + MBG_NET_INTF_LINK_OPT_MASK_CAN_AUTONEG = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_AUTONEG ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_AUTONEG + MBG_NET_INTF_LINK_OPT_MASK_CAN_NTP_HW_TS = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_NTP_HW_TS ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_NTP_HW_TS + MBG_NET_INTF_LINK_OPT_MASK_CAN_PTP_HW_TS = ( 1UL << MBG_NET_INTF_LINK_OPT_CAN_PTP_HW_TS ), ///< See ::MBG_NET_INTF_LINK_OPT_CAN_PTP_HW_TS + MBG_NET_INTF_LINK_OPT_MASK_HAS_NTP_LIC = ( 1UL << MBG_NET_INTF_LINK_OPT_HAS_NTP_LIC ), ///< See ::MBG_NET_INTF_LINK_OPT_HAS_NTP_LIC + MBG_NET_INTF_LINK_OPT_MASK_HAS_PTP_LIC = ( 1UL << MBG_NET_INTF_LINK_OPT_HAS_PTP_LIC ), ///< See ::MBG_NET_INTF_LINK_OPT_HAS_PTP_LIC + MBG_NET_INTF_LINK_OPT_MASK_HAS_SYNCE_STATUS = ( 1UL << MBG_NET_INTF_LINK_OPT_HAS_SYNCE_STATUS ) ///< See ::MBG_NET_INTF_LINK_OPT_HAS_SYNCE_STATUS }; /** - * @brief Network link roles + * @brief Network interface link bonding mode + * + * Used with ::MBG_NET_INTF_LINK_SETTINGS::bond_mode * - * Used with ::MBG_NET_LINK_SETTINGS::role to determine - * if a network link operates in normal mode, or in - * a special mode, e.g. as part of a higher level pseudo - * interface (bonding, etc.) + * @note if_bonding.h contains bonding modes under Linux, found no hint under Windows. + * BUT: Something similiar (concerning naming) can be configured under Windows + * via GUI in device manager, if supported. */ -enum MBG_NET_LINK_ROLES +enum MBG_NET_INTF_LINK_BOND_MODES { - MBG_NET_LINK_ROLE_UNKNOWN, ///< role can't be determined - MBG_NET_LINK_ROLE_NORMAL, ///< link is normal physical interface - MBG_NET_LINK_ROLE_MASTER, ///< link is master (e.g. bonding) - MBG_NET_LINK_ROLE_SLAVE, ///< link is slave (e.g. bonding) - N_MBG_NET_LINK_ROLES + MBG_NET_INTF_LINK_BOND_MODE_ROUNDROBIN, + MBG_NET_INTF_LINK_BOND_MODE_ACTIVEBACKUP, + MBG_NET_INTF_LINK_BOND_MODE_XOR, + MBG_NET_INTF_LINK_BOND_MODE_BROADCAST, + MBG_NET_INTF_LINK_BOND_MODE_8023AD, + MBG_NET_INTF_LINK_BOND_MODE_TLB, + MBG_NET_INTF_LINK_BOND_MODE_ALB, + N_MBG_NET_INTF_LINK_BOND_MODES }; -//##++++++++++++++++ TODO define masks? /** - * @brief Network link bonding bits + * @brief Network interface link bonding mode masks * - * @see SIOCGIFPFLAGS under Linux, found no hint under Windows + * @see ::MBG_NET_INTF_LINK_BOND_MODES */ -enum MBG_NET_LINK_ROLE_BITS +enum MBG_NET_INTF_LINK_BOND_MODE_MASKS { - MBG_NET_LINK_ROLE_BIT_BONDING, ///< Bonding master - MBG_NET_LINK_ROLE_BIT_BOND_SLAVE_INACTIVE, ///< Bonding slave is not active - MBG_NET_LINK_ROLE_BIT_BOND_MASTER_8023AD, ///< 802.3ad bonding master - MBG_NET_LINK_ROLE_BIT_BOND_MASTER_ALB, ///< Balanced-alb bonding master - N_MBG_NET_LINK_ROLE_BITS + MBG_NET_INTF_LINK_BOND_MODE_MASK_ROUNDROBIN = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_ROUNDROBIN ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_ROUNDROBIN + MBG_NET_INTF_LINK_BOND_MODE_MASK_ACTIVEBACKUP = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_ACTIVEBACKUP ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_ACTIVEBACKUP + MBG_NET_INTF_LINK_BOND_MODE_MASK_XOR = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_XOR ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_XOR + MBG_NET_INTF_LINK_BOND_MODE_MASK_BROADCAST = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_BROADCAST ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_BROADCAST + MBG_NET_INTF_LINK_BOND_MODE_MASK_8023AD = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_8023AD ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_8023AD + MBG_NET_INTF_LINK_BOND_MODE_MASK_TLB = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_TLB ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_TLB + MBG_NET_INTF_LINK_BOND_MODE_MASK_ALB = ( 1UL << MBG_NET_INTF_LINK_BOND_MODE_ALB ), ///< See ::MBG_NET_INTF_LINK_BOND_MODE_ALB }; + /** - * @brief Network link role masks + * @brief Network interface link bonding mode name strings * - * @see ::MBG_NET_LINK_ROLE_BITS + * @see ::MBG_NET_INTF_LINK_BOND_MODES */ -enum MBG_NET_LINK_ROLE_MASKS -{ - MBG_NET_LINK_ROLE_MASK_BONDING = ( 1UL << MBG_NET_LINK_ROLE_BIT_BONDING ), ///< see ::MBG_NET_LINK_ROLE_BIT_BONDING - MBG_NET_LINK_ROLE_MASK_BOND_SLAVE_INACTIVE = ( 1UL << MBG_NET_LINK_ROLE_BIT_BOND_SLAVE_INACTIVE ), ///< see ::MBG_NET_LINK_ROLE_BIT_BOND_SLAVE_INACTIVE - MBG_NET_LINK_ROLE_MASK_BOND_MASTER_8023AD = ( 1UL << MBG_NET_LINK_ROLE_BIT_BOND_MASTER_8023AD ), ///< see ::MBG_NET_LINK_ROLE_BIT_BOND_MASTER_8023AD - MBG_NET_LINK_ROLE_MASK_BOND_MASTER_ALB = ( 1UL << MBG_NET_LINK_ROLE_BIT_BOND_MASTER_ALB ), ///< see ::MBG_NET_LINK_ROLE_BIT_BOND_MASTER_ALB - N_MBG_NET_LINK_ROLE_MASKS -}; +#define MBG_NET_INTF_LINK_BOND_MODE_STRS \ +{ \ + "Round Robin", \ + "Active Backup", \ + "XOR", \ + "Broadcast", \ + "802.3ad (LACP)", \ + "TLB", \ + "ALB" \ +} /** - * @brief Network link bonding mode + * @brief Network interface link bonding states * - * Used with ::MBG_NET_LINK_SETTINGS::role_value - * - * @note if_bonding.h contains bonding modes under Linux, found no hint under Windows. - * BUT: Something similiar (concerning naming) can be configured under Windows - * via GUI in device manager, if supported. + * Used with ::MBG_NET_INTF_LINK_SETTINGS::bond_state */ -enum MBG_NET_LINK_BOND_MODES +enum MBG_NET_INTF_LINK_BOND_STATES { - MBG_NET_LINK_BOND_MODE_UNKNOWN, - MBG_NET_LINK_BOND_MODE_ROUNDROBIN, - MBG_NET_LINK_BOND_MODE_ACTIVEBACKUP, - MBG_NET_LINK_BOND_MODE_XOR, - MBG_NET_LINK_BOND_MODE_BROADCAST, - MBG_NET_LINK_BOND_MODE_8023AD, - MBG_NET_LINK_BOND_MODE_TLB, - MBG_NET_LINK_BOND_MODE_ALB, - N_MBG_NET_LINK_BOND_MODES + MBG_NET_INTF_LINK_BOND_STATE_ACTIVE, + MBG_NET_INTF_LINK_BOND_STATE_BACKUP, + N_MBG_NET_INTF_LINK_BOND_STATES }; /** - * @brief Network logical interface commands + * @brief Network interface link type bits + * + * Used with ::MBG_NET_INTF_LINK_SETTINGS::type * - * Used with ::MBG_NET_INTF_SETTINGS::cmd + * @see ::MBG_NET_INTF_LINK_TYPE_MASKS */ -enum MBG_NET_LOG_INTF_CMDS +enum MBG_NET_INTF_LINK_TYPES { - MBG_NET_LOG_CMD_NONE, - MBG_NET_LOG_CMD_ADD_UPDATE, - MBG_NET_LOG_CMD_REMOVE, - N_MBG_NET_LOG_CMDS + MBG_NET_INTF_LINK_TYPE_PHYS, ///< Real physical network interface + MBG_NET_INTF_LINK_TYPE_VLAN, ///< VLAN interface, assigned to physical interface + MBG_NET_INTF_LINK_TYPE_BOND, ///< Bonding interface, which acts as bonding master + N_MBG_NET_INTF_LINK_TYPE_BITS }; /** - * @brief Network logical interface roles + * @brief Network interface link type masks * - * Used with ::MBG_NET_INTF_SETTINGS::role + * Used with ::MBG_NET_INTF_LINK_INFO::supp_types + * + * @see ::MBG_NET_INTF_LINK_TYPES */ -enum MBG_NET_LOG_INTF_ROLES +enum MBG_NET_INTF_LINK_TYPE_MASKS { - MBG_NET_LOG_ROLE_STANDARD, - MBG_NET_LOG_ROLE_BOND, - MBG_NET_LOG_ROLE_VLAN, - N_MBG_NET_INTF_ROLE + MBG_NET_INTF_LINK_TYPE_MASK_PHYS = ( 1UL << MBG_NET_INTF_LINK_TYPE_PHYS ), ///< See ::MBG_NET_INTF_LINK_TYPE_PHYS + MBG_NET_INTF_LINK_TYPE_MASK_VLAN = ( 1UL << MBG_NET_INTF_LINK_TYPE_VLAN ), ///< See ::MBG_NET_INTF_LINK_TYPE_VLAN + MBG_NET_INTF_LINK_TYPE_MASK_BOND = ( 1UL << MBG_NET_INTF_LINK_TYPE_BOND ) ///< See ::MBG_NET_INTF_LINK_TYPE_BOND }; /** - * @brief Network interface bits + * @brief Network interface address bits * - * @see ::MBG_NET_INTF_MASKS + * @see ::MBG_NET_INTF_ADDR_MASKS * - * Used with ::MBG_NET_INTF_INFO::supp_flags + * Used with ::MBG_NET_INTF_ADDR_INFO::supp_flags and ::MBG_NET_INTF_ADDR_SETTINGS::flags */ -enum MBG_NET_INTF_BITS +enum MBG_NET_INTF_ADDR_BITS { - MBG_NET_INTF_BIT_EXT_ROUTING, - N_MBG_NET_INTF_BITS + MBG_NET_INTF_ADDR_BIT_DHCP4, ///< Address has been automatically assigned by DHCP via IPv4 + MBG_NET_INTF_ADDR_BIT_DHCP6, ///< Address has been automatically assigned by DHCP via IPv6 + MBG_NET_INTF_ADDR_BIT_AUTOCONF, ///< Address is an autoconf address, which should be ignored in the configuration + N_MBG_NET_INTF_ADDR_FLAGS }; + /** - * @brief Network interface masks + * @brief Network interface address masks * - * @see ::MBG_NET_INTF_BITS + * @see ::MBG_NET_INTF_ADDR_BITS */ -enum MBG_NET_INTF_MASKS +enum MBG_NET_INTF_ADDR_MASKS { - MBG_NET_INTF_MASK_EXT_ROUTING = ( 1UL << MBG_NET_INTF_BIT_EXT_ROUTING ) ///< see ::MBG_NET_INTF_BIT_EXT_ROUTING + MBG_NET_INTF_ADDR_MASK_DHCP4 = ( 1UL << MBG_NET_INTF_ADDR_BIT_DHCP4 ), ///< See ::MBG_NET_INTF_ADDR_BIT_DHCP4 + MBG_NET_INTF_ADDR_MASK_DHCP6 = ( 1UL << MBG_NET_INTF_ADDR_BIT_DHCP6 ), ///< See ::MBG_NET_INTF_ADDR_BIT_DHCP6 + MBG_NET_INTF_ADDR_MASK_AUTOCONF = ( 1UL << MBG_NET_INTF_ADDR_BIT_AUTOCONF ) ///< See ::MBG_NET_INTF_ADDR_BIT_AUTOCONF +}; + + +enum MBG_NET_INTF_ROUTE_TYPES +{ + MBG_NET_INTF_ROUTE_TYPE_UNKNOWN, + MBG_NET_INTF_ROUTE_TYPE_DEFAULT_GATEWAY, + MBG_NET_INTF_ROUTE_TYPE_DEST_GATEWAY, + MBG_NET_INTF_ROUTE_TYPE_DEST_ADDR, + N_MBG_NET_INTF_ROUTE_TYPES }; /** @} defgroup group_ext_net_cfg_types */ @@ -7857,18 +12668,24 @@ enum MBG_NET_INTF_MASKS */ typedef struct { - MBG_HOSTNAME hostname; ///< hostname, eventually FQDN including domain name - uint32_t reserved; ///< currently reserved, always 0 - uint32_t flags; ///< currently reserved, always 0 - //##++++ TODO: flags could control IPv6, enable forwarding, etc. + MBG_HOSTNAME hostname; ///< hostname, eventually FQDN including domain name + + uint8_t num_intf_link; ///< number of detected/configured physical network interfaces (links), see ::MBG_NET_INTF_LINK_INFO_IDX + uint8_t num_intf_addr; ///< number of configured interface addresses, see ::MBG_NET_INTF_ADDR_INFO_IDX + uint8_t num_dns_srvr; ///< number of configured DNS servers, see ::MBG_IP_ADDR_IDX + uint8_t num_dns_srch_dom; ///< number of configured DNS search domains, see ::MBG_NET_NAME_IDX + uint8_t num_intf_route; ///< number of configured interface routes, see ::MBG_NET_INTF_ROUTE_INFO_IDX + + uint8_t reserved; ///< currently reserved, always 0 + uint16_t flags; ///< currently reserved, always 0 } MBG_NET_GLB_CFG_SETTINGS; -#define _mbg_swab_net_glb_cfg_settings( _p ) \ -{ \ - _mbg_swab32( &(_p)->reserved ); \ - _mbg_swab32( &(_p)->flags ); \ -} +#define _mbg_swab_net_glb_cfg_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) /** @@ -7877,45 +12694,47 @@ typedef struct typedef struct { MBG_NET_GLB_CFG_SETTINGS glb_settings; - uint16_t num_link; ///< max. supported links (physical interfaces), see ::MBG_NET_LINK_SETTINGS_IDX, ::MBG_NET_LINK_INFO_IDX - uint16_t num_intf; ///< max. logical (including virtual) interfaces, see ::MBG_NET_INTF_SETTINGS_IDX, ::MBG_NET_INTF_INFO_IDX - uint16_t num_dns_srvr; ///< max. configurable DNS server addresses, using ::MBG_IP_ADDR_IDX records - uint16_t num_dns_srch_dom; ///< max. configurable DNS search domain records, using ::MBG_NET_NAME_IDX records - uint16_t num_static_routes; ///< max. configurable static routes - uint16_t max_hostname_len; ///< max. length of hostname including trailing 0; if set to 0, max. length is 256 (see rfc1123) - uint32_t reserved_1; ///< currently reserved, always 0 - uint32_t reserved_2; ///< currently reserved, always 0 - uint32_t flags_1; ///< currently reserved, always 0 - uint32_t flags_2; ///< currently reserved, always 0 + uint16_t n_supp_intf_link; ///< max. number of supported physical network interfaces (links), see ::MBG_NET_INTF_LINK_SETTINGS_IDX, ::MBG_NET_INTF_LINK_INFO_IDX + uint16_t n_supp_intf_addr; ///< max. number of supported interface addresses, see ::MBG_NET_INTF_ADDR_SETTINGS_IDX, ::MBG_NET_INTF_ADDR_INFO_IDX + uint16_t n_supp_dns_srvr; ///< max. number of supported DNS server addresses, using ::MBG_IP_ADDR_IDX records + uint16_t n_supp_dns_srch_dom; ///< max. number of supported DNS search domain records, using ::MBG_NET_NAME_IDX records + uint16_t n_supp_intf_route; ///< max. number of supported interface routes, see ::MBG_NET_INTF_ROUTE_SETTINGS_IDX, ::MBG_NET_INTF_ROUTE_INFO_IDX + uint16_t max_hostname_len; ///< max. length of hostname including trailing 0; if set to 0, max. length is 256 (see rfc1123) + uint32_t reserved_1; ///< currently reserved, always 0 + uint32_t reserved_2; ///< currently reserved, always 0 + uint32_t feat_flags; ///< Feature flags, see ::MBG_NET_GLB_CFG_INFO_MASKS + uint32_t flags_2; ///< currently reserved, always 0 } MBG_NET_GLB_CFG_INFO; #define _mbg_swab_net_glb_cfg_info( _p ) \ +do \ { \ _mbg_swab_net_glb_cfg_settings( &(_p)->glb_settings ); \ - _mbg_swab16( &(_p)->num_link ); \ - _mbg_swab16( &(_p)->num_intf ); \ - _mbg_swab16( &(_p)->num_dns_srvr ); \ - _mbg_swab16( &(_p)->num_dns_srch_dom ); \ - _mbg_swab16( &(_p)->num_static_routes ); \ + _mbg_swab16( &(_p)->n_supp_intf_link ); \ + _mbg_swab16( &(_p)->n_supp_intf_addr ); \ + _mbg_swab16( &(_p)->n_supp_dns_srvr ); \ + _mbg_swab16( &(_p)->n_supp_dns_srch_dom ); \ + _mbg_swab16( &(_p)->n_supp_intf_route ); \ _mbg_swab16( &(_p)->max_hostname_len ); \ _mbg_swab32( &(_p)->reserved_1 ); \ _mbg_swab32( &(_p)->reserved_2 ); \ - _mbg_swab32( &(_p)->flags_1 ); \ + _mbg_swab32( &(_p)->feat_flags ); \ _mbg_swab32( &(_p)->flags_2 ); \ -} +} while ( 0 ) + /** * @brief An IPv4 or IPv6 network address */ -typedef struct +typedef struct mbg_ip_addr_s { - uint8_t type; ///< see ::MBG_IP_ADDR_TYPES + uint8_t type; ///< See ::MBG_IP_ADDR_TYPES uint8_t reserved_1; ///< reserved, currently always 0 @todo Do we need this as scope indicator? uint16_t reserved_2; ///< reserved, currently always 0 - union + union u_addr { IP4_ADDR ip4_addr; ///< IPv4 address if ::MBG_IP_ADDR::type == MBG_IP_ADDR_TYPE_IP4 IP6_ADDR ip6_addr; ///< IPv6 address if ::MBG_IP_ADDR::type == MBG_IP_ADDR_TYPE_IP6 @@ -7923,17 +12742,68 @@ typedef struct } MBG_IP_ADDR; +#define _mbg_swab_ip_addr( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->type ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + \ + switch ( (_p)->type ) \ + { \ + case MBG_IP_ADDR_TYPE_IP4: \ + _mbg_swab_ip4_addr( &(_p)->u_addr.ip4_addr ); \ + break; \ + \ + case MBG_IP_ADDR_TYPE_IP6: \ + _mbg_swab_ip6_addr( &(_p)->u_addr.ip6_addr ); \ + break; \ + } \ + \ +} while ( 0 ) + + /** * @brief An IPv4 or IPv6 network address, plus index */ typedef struct { - uint16_t idx; + MBG_MSG_IDX idx; MBG_IP_ADDR addr; ///< network address } MBG_IP_ADDR_IDX; +#define _mbg_swab_ip_addr_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_ip_addr( &(_p)->addr ); \ +} while ( 0 ) + + +/** + * @brief An IPv4 or IPv6 network address plus UDP or TCP port number + */ +typedef struct +{ + MBG_IP_ADDR addr; ///< See ::MBG_IP_ADDR + + uint16_t port; ///< UDP or TCP port + uint16_t flags; ///< currently always 0 + //##+++++ TODO should the flags field indicate if the port is UDP and/or TCP? + +} MBG_IP_ADDR_PORT; + +#define _mbg_swab_ip_addr_port( _p ) \ +do \ +{ \ + _mbg_swab_ip_addr( &(_p)->addr ); \ + _mbg_swab16( &(_p)->port ); \ + _mbg_swab16( &(_p)->flags ); \ +} while ( 0 ) + + /** * @brief Network host or domain name @@ -7944,66 +12814,151 @@ typedef struct } MBG_NET_NAME; +#define _mbg_swab_net_name( _p ) \ +do \ +{ \ + _mbg_swab_mbg_host_name( &(_p)->name ); \ +} while ( 0 ) + + /** * @brief Network host or domain name, plus index */ typedef struct { - uint16_t idx; + MBG_MSG_IDX idx; MBG_NET_NAME net_name; } MBG_NET_NAME_IDX; +#define _mbg_swab_net_name_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_name( &(_p)->net_name ); \ +} while ( 0 ) + + +enum MBG_NET_INTF_SYNC_E_FLAGS +{ + MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_ACTIVE, ///< Indicates, whether SyncE is activated + MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_AUTO_QL, ///< Indicates, whether the quality level is determined automatically, + ///< otherwise, the fixed input/output SSMs are being used + N_MBG_NET_INTF_SYNC_E_FLAGS + +}; + + +enum MBG_NET_INTF_SYNC_E_FLAG_MASKS +{ + MBG_NET_INTF_SYNC_E_FLAG_MASK_SYNC_E_ACTIVE = ( 1UL << MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_ACTIVE ), ///< See ::MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_ACTIVE + MBG_NET_INTF_SYNC_E_FLAG_MASK_SYNC_E_AUTO_QL = ( 1UL << MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_AUTO_QL ) ///< See ::MBG_NET_INTF_SYNC_E_FLAG_SYNC_E_AUTO_QL + +}; + + +typedef struct +{ + uint8_t flags; ///< SyncE flags, see ::MBG_NET_INTF_SYNC_E_FLAG_MASKS + uint8_t min_input_ssm; ///< minimum accepted SSM-QL as synchronization input + uint8_t fixed_input_ssm; ///< assumed SSM value for SyncE input (0xFF if taken from network) + ///< or currently incoming SSM in status structs + uint8_t fixed_output_ssm; ///< Fixed SSM output override + + uint8_t current_output_ssm; ///< current quality level for SyncE output (automatically assigned or fixed) + ///< or currently outgoing SSM in status structs + uint8_t sdh_net_opt; ///< SDH network option, see ::SDH_NETWORK_OPTIONS and ::MBG_NET_INTF_LINK_INFO::supp_sdh_net_opts + uint8_t gb_copper_mode; ///< GBit link copper mode, see ::GBIT_LINK_COPPER_MODES and ::MBG_NET_INTF_LINK_INFO::supp_gb_copper_modes + uint8_t local_priority; ///< user defined priority value (0-255) + +} MBG_NET_INTF_SYNC_E_SETTINGS; /** - * @brief Link (physical interface) specific settings + * @brief Physical network interface link specific settings */ typedef struct { - MBG_MAC_ADDR mac_addr; ///< Physical hardware address - MBG_MAC_ADDR broadcast; ///< Physical broadcast address - uint32_t mtu; ///< Max. packet size in bytes - uint32_t states; ///< see ::MBG_NET_LINK_STATE_BITS - uint32_t flags; ///< Reserved, currently 0 - uint32_t reserved_1; ///< Reserved, currently 0 - uint32_t reserved_2; ///< Reserved, currently 0 - uint16_t bond_idx; ///< Current primary slave link index in ::MBG_NET_LINK_ROLE_MASTER role, - ///< current bonding master link index in ::MBG_NET_LINK_ROLE_SLAVE role, - ///< otherwise reserved and usually 0. - uint8_t speed_mode; ///< see ::MBG_NET_LINK_MODES - uint8_t port; ///< see ::MBG_NET_LINK_PORTS - uint8_t role; ///< see ::MBG_NET_LINK_ROLES - uint8_t reserved[3]; ///< Alignment. Can be used in future for usefull stuff. -//##+++++ TODO check reserved above - uint32_t role_flags; ///< see ::MBG_NET_LINK_ROLE_BITS - uint32_t role_value; ///< Additional role parameters depending on role and role_flags, - ///< e.g. if role is master and flags contain bonding. - ///< See ::MBG_NET_LINK_BOND_MODES. -} MBG_NET_LINK_SETTINGS; - -#define _mbg_swab_net_link_settings( _p ) \ + char name[MBG_IFNAMSIZ]; ///< Interface name + MBG_MAC_ADDR mac_addr; ///< Physical hardware address + MBG_MAC_ADDR broadcast; ///< Physical broadcast address + + uint32_t if_index; ///< Interface index assigned by the kernel + uint32_t common_if_index; ///< Common interface index assigned by the lib (associated with the MAC address), + ///< Valid if ::MBG_NET_INTF_LINK_SETTINGS::type is ::MBG_NET_INTF_LINK_TYPE_PHYS + uint32_t ass_if_index; ///< Interface index of the associated physical interface link, + ///< Valid if ::MBG_NET_INTF_LINK_SETTINGS::type is ::MBG_NET_INTF_LINK_TYPE_VLAN + + uint32_t reserved_1; ///< Reserved, currently 0 + uint32_t states; ///< see @ref MBG_NET_INTF_LINK_STATE_MASKS + + uint32_t hw_type; ///< Hardware type of interface (see ::MBG_NET_HW_TYPES) + uint32_t mtu; ///< Max. packet size in bytes + uint32_t txqlen; ///< Transmission queue length (number of packets) + uint32_t speed; ///< Link speed in MBit/s + + uint8_t type; ///< See ::MBG_NET_INTF_LINK_TYPES + uint8_t duplex; ///< Duplex mode, half (0) or full (1) + uint8_t autoneg; ///< Indicates, whether autonegotiation is enabled or disabled + uint8_t port_type; ///< See ::MBG_NET_INTF_LINK_PORT_TYPES + + uint8_t bond_mode; ///< Bonding mode, see ::MBG_NET_INTF_LINK_BOND_MODES + ///< Valid if ::MBG_NET_INTF_LINK_STATE_MASK_MASTER is set in ::MBG_NET_INTF_LINK_SETTINGS::states + uint8_t bond_state; ///< Status of this interface in the bonding group, see ::MBG_NET_INTF_LINK_BOND_STATES + ///< Valid if MBG_NET_INTF_LINK_STATE_MASK_SLAVE is set in ::MBG_NET_INTF_LINK_SETTINGS::states + uint16_t bond_idx; ///< Interface index of the bonding master link, see ::MBG_NET_INTF_LINK_SETTINGS::if_index + ///< Valid, if MBG_NET_INTF_LINK_STATE_MASK_SLAVE is set in ::MBG_NET_INTF_LINK_SETTINGS::states + + uint16_t vlan_cfg; ///< VLAN configuration options, see ::MBG_VLAN_CFG + ///< Valid if ::MBG_NET_INTF_LINK_SETTINGS::type is ::MBG_NET_INTF_LINK_TYPE_VLAN + uint16_t reserved_2; ///< Reserved, currently 0 + + MBG_NET_INTF_SYNC_E_SETTINGS sync_e; ///< SyncE settings for this port, only valid if ::MBG_NET_INTF_LINK_OPT_MASK_CAN_SYNCE_IN or + ///< ::MBG_NET_INTF_LINK_OPT_MASK_CAN_SYNCE_OUT is set in ::MBG_NET_INTF_LINK_INFO::supp_opts + ///< For network status structs, this can also be the SyncE status, if ::MBG_NET_INTF_LINK_OPT_HAS_SYNCE_STATUS + ///< is set in ::MBG_NET_INTF_LINK_INFO::supp_opts + +} MBG_NET_INTF_LINK_SETTINGS; + +#define _mbg_swab_net_intf_link_settings( _p ) \ +do \ { \ - _mbg_swab32( &(_p)->mtu ); \ - _mbg_swab32( &(_p)->states ); \ + _mbg_swab32( &(_p)->if_index ); \ + _mbg_swab32( &(_p)->common_if_index ); \ + _mbg_swab32( &(_p)->ass_if_index ); \ _mbg_swab32( &(_p)->flags ); \ - _mbg_swab32( &(_p)->reserved_1 ); \ - _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->states ); \ + _mbg_swab32( &(_p)->hw_type ); \ + _mbg_swab32( &(_p)->mtu ); \ + _mbg_swab32( &(_p)->txqlen ); \ + _mbg_swab32( &(_p)->speed ); \ _mbg_swab16( &(_p)->bond_idx ); \ - _mbg_swab32( &(_p)->role_flags ); \ - _mbg_swab32( &(_p)->role_value ); \ -} + _mbg_swab16( &(_p)->vlan_cfg ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + /** * @brief Link (physical interface) specific settings, plus index */ typedef struct { - uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_INFO::num_link-1 - MBG_NET_LINK_SETTINGS settings; + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_INFO::n_supp_intf_link-1. + MBG_NET_INTF_LINK_SETTINGS settings; + +} MBG_NET_INTF_LINK_SETTINGS_IDX; + +#define _mbg_swab_net_intf_link_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_link_settings( &(_p)->settings ); \ +} while ( 0 ) -} MBG_NET_LINK_SETTINGS_IDX; /** @@ -8011,146 +12966,531 @@ typedef struct */ typedef struct { - MBG_NET_LINK_SETTINGS link_settings; ///< see ::MBG_NET_LINK_SETTINGS - uint32_t supp_opts; ///< see ::MBG_NET_LINK_OPT_MASKS - uint32_t supp_speed_modes; ///< see ::MBG_NET_LINK_MODE_MASKS - uint32_t supp_link_ports; ///< see ::MBG_NET_LINK_PORT_MASKS - uint32_t supp_states; ///< see ::MBG_NET_LINK_STATE_MASKS + MBG_NET_INTF_LINK_SETTINGS link_settings; ///< See ::MBG_NET_INTF_LINK_SETTINGS + uint16_t supp_sdh_net_opts; ///< supported SDH network options for SyncE, see ::SDH_NETWORK_OPTION_MASKS + uint16_t supp_gb_copper_modes; ///< supported GBit link copper modes for SyncE, see ::GBIT_LINK_COPPER_MODE_MASKS + uint32_t supp_states; ///< see @ref MBG_NET_INTF_LINK_STATE_MASKS + uint32_t supp_types; ///< See ::MBG_NET_INTF_LINK_TYPE_MASKS + uint32_t supp_speed_modes; ///< see @ref MBG_NET_INTF_LINK_SPEED_MODE_MASKS + uint32_t supp_port_types; ///< See ::MBG_NET_INTF_LINK_PORT_TYPE_MASKS + uint32_t supp_opts; ///< See ::MBG_NET_INTF_LINK_OPT_MASKS + uint32_t supp_bond_modes; ///< See ::MBG_NET_INTF_LINK_BOND_MODE_MASKS + uint16_t lic_ntp_clients; ///< number of supported NTP clients, only valid if ::MBG_NET_INTF_LINK_OPT_MASK_HAS_NTP_LIC + uint16_t lic_ptp_clients; ///< number of supported PTP clients, only valid if ::MBG_NET_INTF_LINK_OPT_MASK_HAS_PTP_LIC + uint32_t reserved_1; uint32_t reserved_2; uint32_t reserved_3; +} MBG_NET_INTF_LINK_INFO; + +#define _mbg_swab_net_intf_link_info( _p ) \ +do \ +{ \ + _mbg_swab_net_intf_link_settings( &(_p)->link_settings ); \ + _mbg_swab16( &(_p)->supp_sdh_net_opts ); \ + _mbg_swab16( &(_p)->supp_gb_copper_mds ); \ + _mbg_swab32( &(_p)->supp_states ); \ + _mbg_swab32( &(_p)->supp_types ); \ + _mbg_swab32( &(_p)->supp_speed_modes ); \ + _mbg_swab32( &(_p)->supp_port_types ); \ + _mbg_swab32( &(_p)->supp_opts ); \ + _mbg_swab32( &(_p)->supp_bond_modes ); \ + _mbg_swab16( &(_p)->lic_ntp_clients ); \ + _mbg_swab16( &(_p)->lic_ptp_clients ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief Query MBG_NET_INTF_LINK_INFO by its index + */ +typedef struct mbg_net_intf_link_info_idx_s +{ + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_link-1. + MBG_NET_INTF_LINK_INFO info; ///< See ::MBG_NET_INTF_LINK_INFO. + +} MBG_NET_INTF_LINK_INFO_IDX; + +#define _mbg_swab_net_intf_link_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_link_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief Network interface address specific settings, flags and supported features + * + * @note Use if_index to identify uniquely its associated network link. + */ +typedef struct +{ + char label[MBG_IFNAMSIZ]; ///< Interface label + + uint32_t addr_index; ///< Index of the address on the physical interface it is assigned to + uint32_t ass_if_index; ///< Index of the associated interface link, see ::MBG_NET_INTF_LINK_SETTINGS::if_index + + uint32_t flags; ///< See ::MBG_NET_INTF_ADDR_MASKS + + MBG_IP_ADDR ip; ///< IP address associated with this interface + MBG_IP_ADDR broadcast; ///< Broadcast address associated with this interface + + uint8_t prefix_bits; ///< Number of subnet mask bits for CIDR notation, e.g. 24 for /24 + uint8_t reserved_1; ///< Reserved, currently 0 + uint16_t reserved_2; ///< Reserved, currently 0 + + uint32_t reserved_3; ///< Reserved, currently 0 + uint32_t reserved_4; ///< Reserved, currently 0 + uint32_t reserved_5; ///< Reserved, currently 0 + +} MBG_NET_INTF_ADDR_SETTINGS; + +#define _mbg_swab_net_intf_addr_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->addr_index ); \ + _mbg_swab32( &(_p)->ass_if_index ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab_ip_addr( &(_p)->ip ); \ + _mbg_swab_ip_addr( &(_p)->broadcast ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ +} while ( 0 ) + -} MBG_NET_LINK_INFO; +/** + * @brief Query MBG_NET_INTF_ADDR_SETTINGS by its index + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_addr-1. + MBG_NET_INTF_ADDR_SETTINGS settings; ///< See ::MBG_NET_INTF_ADDR_SETTINGS. -#define _mbg_swab_net_link_info( _p ) \ +} MBG_NET_INTF_ADDR_SETTINGS_IDX; + +#define _mbg_swab_net_intf_addr_settings_idx( _p ) \ +do \ { \ - _mbg_swab_net_link_settings( &(_p)->link_settings ); \ - _mbg_swab32( &(_p)->supp_opts ); \ - _mbg_swab32( &(_p)->supp_speed_modes ); \ - _mbg_swab32( &(_p)->supp_link_ports ); \ - _mbg_swab32( &(_p)->supp_states ); \ - _mbg_swab32( &(_p)->reserved_2 ); \ - _mbg_swab32( &(_p)->reserved_3 ); \ -} + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_addr_settings( &(_p)->settings ); \ +} while ( 0 ) /** - * @brief Query MBG_NET_LINK_INFO by its index + * @brief Network interface address specific settings, flags and supported features */ typedef struct { - uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_INFO::num_link-1 - MBG_NET_LINK_INFO info; + MBG_NET_INTF_ADDR_SETTINGS addr_settings; ///< See ::MBG_NET_INTF_ADDR_SETTINGS + uint32_t supp_flags; ///< See ::MBG_NET_INTF_ADDR_MASKS + uint32_t reserved_1; ///< Reserved, currently 0 + uint32_t reserved_2; ///< Reserved, currently 0 + +} MBG_NET_INTF_ADDR_INFO; -} MBG_NET_LINK_INFO_IDX; +#define _mbg_swab_net_intf_addr_info( _p ) \ +do \ +{ \ + _mbg_swab_net_intf_addr_settings( &(_p)->addr_settings ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) /** - * @brief Interface specific settings, flags and supported features - * - * @note Use link_mac and role to identify uniquely its associated network link. + * @brief Query MBG_NET_INTF_ADDR_INFO by its index + */ +typedef struct mbg_net_intf_addr_info_idx_s +{ + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_addr-1. + MBG_NET_INTF_ADDR_INFO info; ///< See ::MBG_NET_INTF_ADDR_INFO. + +} MBG_NET_INTF_ADDR_INFO_IDX; + +#define _mbg_swab_net_intf_addr_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_addr_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief Network interface route specific settings + * + * @note Use link_mac and ass_addr_idx to identify the associated network address and network link (via address) */ typedef struct { - uint8_t cmd; ///< see ::MBG_NET_LOG_INTF_CMDS - uint8_t role; ///< see ::MBG_NET_LOG_INTF_ROLES - uint16_t reserved_1; ///< Reserved, currently 0 - uint32_t role_value; ///< Role specific value. E.g. VLAN ID - uint32_t flags; ///< Reserved, currently 0 - uint32_t reserved_2; ///< Reserved, currently 0 - MBG_IP_ADDR ip; ///< IP address associated with this interface - MBG_IP_ADDR gateway; ///< Interface specific. Reserved for future use. see ::MBG_IP_ADDR and ::MBG_NET_INTF_BIT_EXT_ROUTING - MBG_MAC_ADDR link_mac; ///< Unique identifier for related link (physical) interface - uint8_t prefix; ///< Subnet mask bits for CIDR notation, e.g. /24 - uint8_t reserved_3; ///< Reserved, currently 0 + uint8_t type; ///< Type of the route entry, see ::MBG_NET_INTF_ROUTE_TYPES + uint8_t reserved_1; ///< Reserved, currently 0 + uint16_t reserved_2; ///< Reserved, currently 0 + + MBG_IP_ADDR gateway; ///< Gateway IP address, only used if type is + ///< ::MBG_NET_INTF_ROUTE_TYPE_DEFAULT_GATEWAY or ::MBG_NET_INTF_ROUTE_TYPE_DEST_GATEWAY + MBG_IP_ADDR dst; ///< Destination IP address, only used if ::MBG_NET_INTF_ROUTE_SETTINGS::type is + ///< ::MBG_NET_INTF_ROUTE_TYPE_DEST_GATEWAY or ::MBG_NET_INTF_ROUTE_TYPE_DEST_ADDR + uint8_t dst_prefix_bits; ///< Prefix Bits for the destination address + + uint32_t ass_if_index; ///< Index of the associated interface link, see ::MBG_NET_INTF_LINK_SETTINGS::if_index + uint32_t ass_addr_index; ///< Index of the associated interface address, see ::MBG_NET_INTF_ADDR_SETTINGS::addr_index, + ///< Valid if ::MBG_NET_INTF_ROUTE_SETTINGS::type is ::MBG_NET_INTF_ROUTE_TYPE_DEST_GATEWAY or ::MBG_NET_INTF_ROUTE_TYPE_DEST_ADDR -} MBG_NET_INTF_SETTINGS; + uint32_t reserved_3; ///< Reserved, currently 0 + uint32_t reserved_4; ///< Reserved, currently 0 + uint32_t reserved_5; ///< Reserved, currently 0 + +} MBG_NET_INTF_ROUTE_SETTINGS; + +#define _mbg_swab_net_intf_route_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab_ip_addr( &(_p)->gateway ); \ + _mbg_swab_ip_addr( &(_p)->dst ); \ + _mbg_swab32( &(_p)->ass_if_index ); \ + _mbg_swab32( &(_p)->ass_addr_index ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ +} while ( 0 ) /** - * @brief Query MBG_NET_INTF_INFO by its index + * @brief Query MBG_NET_INTF_ROUTE_SETTINGS by its index */ typedef struct { - uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_INFO::num_intf-1 - MBG_NET_INTF_SETTINGS settings; + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_route-1. + MBG_NET_INTF_ROUTE_SETTINGS settings; ///< See ::MBG_NET_INTF_ROUTE_SETTINGS. -} MBG_NET_INTF_SETTINGS_IDX; +} MBG_NET_INTF_ROUTE_SETTINGS_IDX; + +#define _mbg_swab_net_intf_route_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_route_settings( &(_p)->settings ); \ +} while ( 0 ) /** - * @brief Interface specific settings, flags and supported features + * @brief Network interface address specific settings */ typedef struct { - MBG_NET_INTF_SETTINGS intf_settings; - uint32_t supp_flags; ///< see ::MBG_NET_INTF_MASKS - uint32_t reserved_1; ///< Reserved, currently 0 - uint32_t reserved_2; ///< Reserved, currently 0 + MBG_NET_INTF_ROUTE_SETTINGS route_settings; ///< See ::MBG_NET_INTF_ROUTE_SETTINGS + uint32_t reserved_1; ///< Reserved, currently 0 + uint32_t reserved_2; ///< Reserved, currently 0 + uint32_t reserved_3; ///< Reserved, currently 0 + uint32_t reserved_4; ///< Reserved, currently 0 +} MBG_NET_INTF_ROUTE_INFO; -} MBG_NET_INTF_INFO; +#define _mbg_swab_net_intf_route_info( _p ) \ +do \ +{ \ + _mbg_swab_net_intf_route_settings( &(_p)->route_settings ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ +} while ( 0 ) /** - * @brief Query MBG_NET_INTF_INFO by its index + * @brief Query MBG_NET_INTF_ROUTE_INFO by its index */ typedef struct { - uint16_t idx; ///< 0..::MBG_NET_GLB_CFG_INFO::num_intf-1 - MBG_NET_INTF_INFO info; + MBG_MSG_IDX idx; ///< 0..::MBG_NET_GLB_CFG_SETTINGS::num_intf_route-1. + MBG_NET_INTF_ROUTE_INFO info; ///< See ::MBG_NET_INTF_ROUTE_INFO. + +} MBG_NET_INTF_ROUTE_INFO_IDX; + +#define _mbg_swab_net_intf_route_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_net_intf_route_info( &(_p)->info ); \ +} while ( 0 ) + + +/** @} defgroup group_ext_net_cfg */ + +/** @} defgroup group_net_cfg */ + + -} MBG_NET_INTF_INFO_IDX; /** - * @brief An IPv4 or IPv6 network address plus UDP or TCP port number + * @defgroup group_ucap_net User Captures via Network + * + * @note Group for the user capture via network feature + * Only supported if ::MBG_XFEATURE_UCAP_NET is set in extended features + * Corresponding GPS commands are ::GPS_UCAP_NET_GLB_INFO and ::GPS_UCAP_NET_RECV_INFO_IDX + * + * @{ */ + + +#define MBG_UCAP_NET_DEFAULT_UDP_PORT 50815 + +/** + * @brief Transfer mode for user captures via network + * + * @see ::MBG_UCAP_NET_TRANSF_MODE_MASKS + * + * Used with ::MBG_UCAP_NET_RECV_SETTINGS::mode + */ +enum MBG_UCAP_NET_TRANSF_MODE +{ + MBG_UCAP_NET_TRANSF_MODE_UNKNOWN, ///< Unknown transfer mode + MBG_UCAP_NET_TRANSF_MODE_ON_REQ, ///< User captures will be transferred on request only + MBG_UCAP_NET_TRANSF_MODE_AUTO, ///< User captures are being transferred automatically + N_MBG_UCAP_NET_TRANSF_MODES +}; + + +/** + * @brief Masks for transfer mode used with ::MBG_UCAP_NET_GLB_INFO::supp_modes + * + * @see ::MBG_UCAP_NET_TRANSF_MODE + */ +enum MBG_UCAP_NET_TRANSF_MODE_MASKS +{ + MBG_UCAP_NET_TRANSF_MODE_MASK_UNKNOWN = ( 1UL << MBG_UCAP_NET_TRANSF_MODE_UNKNOWN ), ///< See ::MBG_UCAP_NET_TRANSF_MODE_UNKNOWN + MBG_UCAP_NET_TRANSF_MODE_MASK_ON_REQ = ( 1UL << MBG_UCAP_NET_TRANSF_MODE_ON_REQ ), ///< See ::MBG_UCAP_NET_TRANSF_MODE_ON_REQ + MBG_UCAP_NET_TRANSF_MODE_MASK_AUTO = ( 1UL << MBG_UCAP_NET_TRANSF_MODE_AUTO ) ///< See ::MBG_UCAP_NET_TRANSF_MODE_AUTO +}; + + + +/** + * @brief Transfer protocol for user captures via network + * + * @see ::MBG_UCAP_NET_TRANSF_PROTO_MASKS + * + * Used with ::MBG_UCAP_NET_RECV_SETTINGS::proto + */ +enum MBG_UCAP_NET_TRANSF_PROTO +{ + MBG_UCAP_NET_TRANSF_PROTO_UNKNOWN, ///< Unknown transfer mode + MBG_UCAP_NET_TRANSF_PROTO_UDP, ///< User captures are transferred via UDP + N_MBG_UCAP_NET_TRANSF_PROTOS +}; + + +/** + * @brief Masks for transfer protocol used with ::MBG_UCAP_NET_GLB_INFO::supp_protos + * + * @see ::MBG_UCAP_NET_TRANSF_PROTO + */ +enum MBG_UCAP_NET_TRANSF_PROTO_MASKS +{ + MBG_UCAP_NET_TRANSF_PROTO_MASK_UNKNOWN = ( 1UL << MBG_UCAP_NET_TRANSF_PROTO_UNKNOWN ), ///< See ::MBG_UCAP_NET_TRANSF_PROTO_UNKNOWN + MBG_UCAP_NET_TRANSF_PROTO_MASK_UDP = ( 1UL << MBG_UCAP_NET_TRANSF_PROTO_UDP ) ///< See ::MBG_UCAP_NET_TRANSF_PROTO_UDP +}; + + + +/** + * @brief Supported flags for user captures via network + * + * @see ::MBG_UCAP_NET_SUPP_FLAG_MASKS + */ +enum MBG_UCAP_NET_SUPP_FLAGS +{ + MBG_UCAP_NET_SUPP_FLAG_IPV6, + N_MBG_UCAP_NET_SUPP_FLAGS +}; + + +/** + * @brief Masks for supported flags used with ::MBG_UCAP_NET_GLB_INFO::supp_flags + * + * @see ::MBG_UCAP_NET_TRANSF_PROTO + */ +enum MBG_UCAP_NET_SUPP_FLAG_MASKS +{ + MBG_UCAP_NET_SUPP_FLAG_MASK_IPV6 = ( 1UL << MBG_UCAP_NET_SUPP_FLAG_IPV6 ) ///< See ::MBG_UCAP_NET_SUPP_FLAG_IPV6 +}; + + +/** + * @brief Global settings for user captures via network + * + * @note This structure shall be used to set the current global settings of a device + * with GPS command ::GPS_UCAP_NET_GLB_INFO. */ typedef struct { - MBG_IP_ADDR addr; ///< see ::MBG_IP_ADDR + uint32_t num_recvs; ///< Number of configured network receivers, see ::MBG_UCAP_NET_RECV_INFO_IDX + uint32_t reserved_0; ///< Reserved, currently always 0 + uint32_t reserved_1; ///< Reserved, currently always 0 + uint32_t reserved_2; ///< Reserved, currently always 0 - uint16_t port; ///< UDP or TCP port - uint16_t flags; ///< currently always 0 - //##+++++ TODO should the flags field indicate if the port is UDP and/or TCP? +} MBG_UCAP_NET_GLB_SETTINGS; -} MBG_IP_ADDR_PORT; +#define _mbg_swab_ucap_net_glb_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->num_recvs ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) -#if 0 //##++++++++++++++++++++++ /** - * @brief Network service configuration + * @brief Global settings, features and flags for user captures via network * - * Used to configure known services, e.g SSH, FTP, etc. + * @note This structure shall be used to read the current global settings from a device + * with GPS command ::GPS_UCAP_NET_GLB_INFO. */ typedef struct { - uint16_t svc_type; ///< see ::MBG_NET_SVC_TYPES - uint16_t reserved; ///< reserved, currently always 0 - MBG_IP_ADDR_PORT settings; ///< The network address and port a service listens on - uint32_t flags; ///< reserved, currently always 0 + MBG_UCAP_NET_GLB_SETTINGS settings; ///< See ::MBG_UCAP_NET_GLB_SETTINGS -} MBG_NET_INTF_CFG; + uint32_t n_supp_recvs; ///< Number of supported network receivers, see ::MBG_UCAP_NET_RECV_INFO_IDX + uint32_t supp_modes; ///< Supported transfer modes, see ::MBG_UCAP_NET_TRANSF_MODE_MASKS + uint32_t supp_protos; ///< Supported transfer protocols, see ::MBG_UCAP_NET_TRANSF_PROTO_MASKS + uint32_t reserved_0; ///< Reserved, currently always 0 + uint32_t reserved_1; ///< Reserved, currently always 0 + uint32_t supp_flags; ///< Supported flags, see ::MBG_UCAP_NET_SUPP_FLAG_MASKS + +} MBG_UCAP_NET_GLB_INFO; + + +#define _mbg_swab_ucap_net_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_ucap_net_glb_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->n_supp_recvs ); \ + _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab32( &(_p)->supp_protos ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) /** - * @brief + * @brief Settings for receivers of user captures via network */ typedef struct { - uint8_t b[IP6_ADDR_BYTES]; ///< bytes holding the address bits, b[0] == LSBs -//##+++ uint8_t cidr_net_mask; ///< number of CIDR net mask bits, 0..::IP6_ADDR_BITS -// uint8_t reserved; ///< not yet used, always 0 -// uint16_t flags; ///< not yet used, always 0 + uint8_t mode; ///< Transfer mode, see ::MBG_UCAP_NET_TRANSF_MODE + uint8_t proto; ///< Transfer protocol, see ::MBG_UCAP_NET_TRANSF_PROTO + uint16_t reserved_1; ///< Reserved, currently always 0 -} MBG_NET_INTF_CFG; + uint32_t reserved_2; ///< Reserved, currently always 0 + uint32_t reserved_3; ///< Reserved, currently always 0 + uint32_t ucaps; ///< Bit mask for active user captures -#endif + MBG_IP_ADDR_PORT addr; ///< Destination IP and port address of the network receiver, see ::MBG_IP_ADDR_PORT -/** @} defgroup group_ext_net_cfg */ +} MBG_UCAP_NET_RECV_SETTINGS; -/** @} defgroup group_net_cfg */ + +#define _mbg_swab_ucap_net_recv_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->ucaps ); \ + _mbg_swab_ip_addr_port( &(_p)->addr ); \ +} while ( 0 ) + + + +/** + * @brief Settings for receivers of user captures via network + * + * @note This structure shall be used to write the settings to the device + * with GPS command ::GPS_UCAP_NET_RECV_INFO_IDX. + * This can be done for index 0 to ::MBG_UCAP_NET_GLB_SETTINGS::num_recvs-1. + * + * @see ::MBG_UCAP_NET_RECV_SETTINGS + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0..::MBG_UCAP_NET_GLB_SETTINGS::num_recvs-1. + MBG_UCAP_NET_RECV_SETTINGS settings; ///< See ::MBG_UCAP_NET_RECV_SETTINGS. + +} MBG_UCAP_NET_RECV_SETTINGS_IDX; + + +#define _mbg_swab_ucap_net_recv_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_ucap_net_recv_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Settings, features and flags for receivers of user captures via network + */ +typedef struct +{ + MBG_UCAP_NET_RECV_SETTINGS settings; ///< See ::MBG_UCAP_NET_RECV_SETTINGS + + uint32_t reserved_0; ///< Reserved, currently always 0 + uint32_t reserved_1; ///< Reserved, currently always 0 + uint32_t reserved_2; ///< Reserved, currently always 0 + uint32_t reserved_3; ///< Reserved, currently always 0 + +} MBG_UCAP_NET_RECV_INFO; + + +#define _mbg_swab_ucap_net_recv_info( _p ) \ +do \ +{ \ + _mbg_swab_ucap_net_recv_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief Settings, features and flags for receivers of user captures via network + * + * @note This structure shall be used to read the current settings from the device + * with GPS command ::GPS_UCAP_NET_RECV_INFO_IDX. + * This can be done for index 0 to ::MBG_UCAP_NET_GLB_SETTINGS::num_recvs-1. + * + * @see ::MBG_UCAP_NET_RECV_INFO + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0..::MBG_UCAP_NET_GLB_INFO::n_supp_recvs-1. + MBG_UCAP_NET_RECV_INFO info; ///< See ::MBG_UCAP_NET_RECV_INFO. + +} MBG_UCAP_NET_RECV_INFO_IDX; + + +#define _mbg_swab_ucap_net_recv_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_ucap_net_recv_info( &(_p)->info ); \ +} while ( 0 ) + +/** @} defgroup ext_ucap */ @@ -8184,13 +13524,13 @@ enum PTP_NW_PROTS */ enum PTP_NW_PROT_MASKS { - PTP_NW_PROT_MSK_RESERVED = ( 1UL << PTP_NW_PROT_RESERVED ), ///< see ::PTP_NW_PROT_RESERVED - PTP_NW_PROT_MSK_UDP_IPV4 = ( 1UL << PTP_NW_PROT_UDP_IPV4 ), ///< see ::PTP_NW_PROT_UDP_IPV4 - PTP_NW_PROT_MSK_UDP_IPV6 = ( 1UL << PTP_NW_PROT_UDP_IPV6 ), ///< see ::PTP_NW_PROT_UDP_IPV6 - PTP_NW_PROT_MSK_IEEE_802_3 = ( 1UL << PTP_NW_PROT_IEEE_802_3 ), ///< see ::PTP_NW_PROT_IEEE_802_3 - PTP_NW_PROT_MSK_DEVICE_NET = ( 1UL << PTP_NW_PROT_DEVICE_NET ), ///< see ::PTP_NW_PROT_DEVICE_NET - PTP_NW_PROT_MSK_CONTROL_NET = ( 1UL << PTP_NW_PROT_CONTROL_NET ), ///< see ::PTP_NW_PROT_CONTROL_NET - PTP_NW_PROT_MSK_PROFINET = ( 1UL << PTP_NW_PROT_PROFINET ) ///< see ::PTP_NW_PROT_PROFINET + PTP_NW_PROT_MSK_RESERVED = ( 1UL << PTP_NW_PROT_RESERVED ), ///< See ::PTP_NW_PROT_RESERVED + PTP_NW_PROT_MSK_UDP_IPV4 = ( 1UL << PTP_NW_PROT_UDP_IPV4 ), ///< See ::PTP_NW_PROT_UDP_IPV4 + PTP_NW_PROT_MSK_UDP_IPV6 = ( 1UL << PTP_NW_PROT_UDP_IPV6 ), ///< See ::PTP_NW_PROT_UDP_IPV6 + PTP_NW_PROT_MSK_IEEE_802_3 = ( 1UL << PTP_NW_PROT_IEEE_802_3 ), ///< See ::PTP_NW_PROT_IEEE_802_3 + PTP_NW_PROT_MSK_DEVICE_NET = ( 1UL << PTP_NW_PROT_DEVICE_NET ), ///< See ::PTP_NW_PROT_DEVICE_NET + PTP_NW_PROT_MSK_CONTROL_NET = ( 1UL << PTP_NW_PROT_CONTROL_NET ), ///< See ::PTP_NW_PROT_CONTROL_NET + PTP_NW_PROT_MSK_PROFINET = ( 1UL << PTP_NW_PROT_PROFINET ) ///< See ::PTP_NW_PROT_PROFINET }; @@ -8248,21 +13588,33 @@ enum PTP_PORT_STATES }; +#define PTP_PORT_ST_STR_UNINITIALIZED "Uninitialized" +#define PTP_PORT_ST_STR_INITIALIZED "Initializing" +#define PTP_PORT_ST_STR_FAULTY "Faulty" +#define PTP_PORT_ST_STR_DISABLED "Disabled" +#define PTP_PORT_ST_STR_LISTENING "Listening" +#define PTP_PORT_ST_STR_PREMASTER "Pre-Master" +#define PTP_PORT_ST_STR_MASTER "Master" +#define PTP_PORT_ST_STR_PASSIVE "Passive" +#define PTP_PORT_ST_STR_UNCALIBRATED "Uncalibrated" +#define PTP_PORT_ST_STR_SLAVE "Slave" + + /** * @brief Name strings for the PTP port states */ -#define PTP_PORT_STATE_STRS \ -{ \ - "UNINITIALIZED", \ - "INITIALIZING", \ - "FAULTY", \ - "DISABLED", \ - "LISTENING", \ - "PRE_MASTER", \ - "MASTER", \ - "PASSIVE", \ - "UNCALIBRATED", \ - "SLAVE" \ +#define PTP_PORT_STATE_STRS \ +{ \ + PTP_PORT_ST_STR_UNINITIALIZED, \ + PTP_PORT_ST_STR_INITIALIZED, \ + PTP_PORT_ST_STR_FAULTY, \ + PTP_PORT_ST_STR_DISABLED, \ + PTP_PORT_ST_STR_LISTENING, \ + PTP_PORT_ST_STR_PREMASTER, \ + PTP_PORT_ST_STR_MASTER, \ + PTP_PORT_ST_STR_PASSIVE, \ + PTP_PORT_ST_STR_UNCALIBRATED, \ + PTP_PORT_ST_STR_SLAVE \ } @@ -8303,8 +13655,8 @@ enum PTP_DELAY_MECHS */ enum PTP_DELAY_MECH_MASKS { - PTP_DELAY_MECH_MSK_E2E = ( 1UL << PTP_DELAY_MECH_E2E ), ///< see ::PTP_DELAY_MECH_E2E - PTP_DELAY_MECH_MSK_P2P = ( 1UL << PTP_DELAY_MECH_P2P ) ///< see ::PTP_DELAY_MECH_P2P + PTP_DELAY_MECH_MSK_E2E = ( 1UL << PTP_DELAY_MECH_E2E ), ///< See ::PTP_DELAY_MECH_E2E + PTP_DELAY_MECH_MSK_P2P = ( 1UL << PTP_DELAY_MECH_P2P ) ///< See ::PTP_DELAY_MECH_P2P }; @@ -8358,6 +13710,8 @@ enum PTP_CLOCK_ACCURACIES PTP_CLOCK_ACCURACY_RESERVED_3, PTP_CLOCK_ACCURACY_RESERVED_4, N_PTP_CLOCK_ACCURACY + //##++++ TODO: Add a code for 0xFE (unknown), or eventually + // redesign the lookup of associated strings completely. }; @@ -8459,6 +13813,11 @@ enum PTP_ROLES PTP_ROLE_UNICAST_MASTER, ///< unicast master PTP_ROLE_MULTICAST_AUTO, ///< multicast master or slave (auto selection) PTP_ROLE_BOTH_MASTER, ///< simultanous multicast and unicast master + PTP_ROLE_NTP_SERVER, ///< NTP Unicast Server + PTP_ROLE_NTP_CLIENT, ///< NTP Unicast Client + PTP_ROLE_TIME_MONITOR, ///< Net Sync Monitor for external PTP or NTP devices + PTP_ROLE_V1_MASTER, ///< PTPv1 Master in Multicast mode + PTP_ROLE_V1_SLAVE, ///< PTPv1 Slave in Multicast mode N_PTP_ROLES ///< number of defined roles }; @@ -8479,12 +13838,17 @@ enum PTP_ROLES */ enum PTP_ROLE_MASKS { - PTP_ROLE_MSK_MULTICAST_SLAVE = ( 1UL << PTP_ROLE_MULTICAST_SLAVE ), ///< see ::PTP_ROLE_MULTICAST_SLAVE - PTP_ROLE_MSK_UNICAST_SLAVE = ( 1UL << PTP_ROLE_UNICAST_SLAVE ), ///< see ::PTP_ROLE_UNICAST_SLAVE - PTP_ROLE_MSK_MULTICAST_MASTER = ( 1UL << PTP_ROLE_MULTICAST_MASTER ), ///< see ::PTP_ROLE_MULTICAST_MASTER - PTP_ROLE_MSK_UNICAST_MASTER = ( 1UL << PTP_ROLE_UNICAST_MASTER ), ///< see ::PTP_ROLE_UNICAST_MASTER - PTP_ROLE_MSK_MULTICAST_AUTO = ( 1UL << PTP_ROLE_MULTICAST_AUTO ), ///< see ::PTP_ROLE_MULTICAST_AUTO - PTP_ROLE_MSK_BOTH_MASTER = ( 1UL << PTP_ROLE_BOTH_MASTER ) ///< see ::PTP_ROLE_BOTH_MASTER + PTP_ROLE_MSK_MULTICAST_SLAVE = ( 1UL << PTP_ROLE_MULTICAST_SLAVE ), ///< See ::PTP_ROLE_MULTICAST_SLAVE + PTP_ROLE_MSK_UNICAST_SLAVE = ( 1UL << PTP_ROLE_UNICAST_SLAVE ), ///< See ::PTP_ROLE_UNICAST_SLAVE + PTP_ROLE_MSK_MULTICAST_MASTER = ( 1UL << PTP_ROLE_MULTICAST_MASTER ), ///< See ::PTP_ROLE_MULTICAST_MASTER + PTP_ROLE_MSK_UNICAST_MASTER = ( 1UL << PTP_ROLE_UNICAST_MASTER ), ///< See ::PTP_ROLE_UNICAST_MASTER + PTP_ROLE_MSK_MULTICAST_AUTO = ( 1UL << PTP_ROLE_MULTICAST_AUTO ), ///< See ::PTP_ROLE_MULTICAST_AUTO + PTP_ROLE_MSK_BOTH_MASTER = ( 1UL << PTP_ROLE_BOTH_MASTER ), ///< See ::PTP_ROLE_BOTH_MASTER + PTP_ROLE_MSK_NTP_SERVER = ( 1UL << PTP_ROLE_NTP_SERVER ), ///< See ::PTP_ROLE_NTP_SERVER + PTP_ROLE_MSK_NTP_CLIENT = ( 1UL << PTP_ROLE_NTP_CLIENT ), ///< See ::PTP_ROLE_NTP_CLIENT + PTP_ROLE_MSK_TIME_MONITOR = ( 1UL << PTP_ROLE_TIME_MONITOR ), ///< See ::PTP_ROLE_TIME_MONITOR + PTP_ROLE_MSK_V1_MASTER = ( 1UL << PTP_ROLE_V1_MASTER ), ///< See ::PTP_ROLE_MULTICAST_MASTER + PTP_ROLE_MSK_V1_SLAVE = ( 1UL << PTP_ROLE_V1_SLAVE ) ///< See ::PTP_ROLE_UNICAST_SLAVE }; @@ -8511,7 +13875,12 @@ enum PTP_ROLE_MASKS "Multicast Master", \ "Unicast Master", \ "Multicast (Auto)", \ - "UC+MC Master" \ + "UC+MC Master", \ + "NTP Server", \ + "NTP Client", \ + "Sync Monitor", \ + "V1 Master", \ + "V1 Slave" \ } @@ -8528,7 +13897,12 @@ enum PTP_ROLE_MASKS "MCM", \ "UCM", \ "MCA", \ - "UMM" \ + "UMM", \ + "NSV", \ + "NCL", \ + "MON", \ + "V1M", \ + "V1S" \ } @@ -8538,7 +13912,7 @@ enum PTP_ROLE_MASKS * @note This usually consists of a 6 byte MAC address with * 2 fixed bytes inserted, or all ones as wildcard. */ -typedef struct +typedef struct ptp_clock_id_s { uint8_t b[8]; @@ -8560,6 +13934,163 @@ typedef uint16_t PTP_PORT_ID; /** + * @brief A PTP port identity + * + * @note For further information, see IEEE 1588-2008, chapter 5.3.5 + * + * @see ::PTP_CLOCK_ID + * @see ::PTP_PORT_ID + */ +typedef struct +{ + PTP_CLOCK_ID clock_identity; + PTP_PORT_ID port_number; + +} PTP_PORT_IDENTITY; + + +#define _mbg_swab_ptp_port_identity( _p ) \ +{ \ + _mbg_swab_ptp_clock_id( &(_p)->clock_identity ); \ + _mbg_swab_ptp_port_id( &(_p)->port_number ); \ +} + + +/** + * @brief A PTP port identity + * + * @note For further information, see IEEE 1588-2008, chapter 5.3.5 + * + * @see ::PTP_CLOCK_ID + * @see ::PTP_PORT_ID + */ +typedef struct ptp_ng_port_identity_s +{ + PTP_CLOCK_ID clock_identity; + PTP_PORT_ID port_number; + uint16_t reserved_1; + uint32_t reserved_2; +} PTP_NG_PORT_IDENTITY; + + +#define _mbg_swab_ptp_ng_port_identity( _p ) \ +{ \ + _mbg_swab_ptp_clock_id( &(_p)->clock_identity ); \ + _mbg_swab_ptp_port_id( &(_p)->port_number ); \ +} + + +/** + * @brief PTP clock quality + * + * @note For further information, see IEEE 1588-2008, chapter 5.3.7 + */ +typedef struct +{ + uint8_t clock_class; ///< PTP clock class representing the current sync status + int8_t clock_accuracy; ///< See ::PTP_CLOCK_ACCURACIES + uint16_t log_variance; ///< PTP offset scaled log variance representing the time stability + +} PTP_CLOCK_QUALITY; + + +#define _mbg_swab_ptp_clock_quality( _p ) \ +{ \ + _mbg_swab8( &(_p)->clock_class ); \ + _mbg_swab8( &(_p)->clock_accuracy ); \ + _mbg_swab16( &(_p)->log_variance ); \ +} + + +/** + * @brief PTP time interval + * + * @note For further information, see IEEE 1588-2008, chapter 5.3.2 + */ +typedef struct +{ + int64_t scaled_nanoseconds; + +} PTP_TIME_INTERVAL; + + +#define _mbg_swab_ptp_time_interval( _p ) \ +{ \ + _mbg_swab64( &(_p)->scaled_nanoseconds ); \ +} + + + +/** + * @brief PTP packet timestamp seconds field. + * + * PTP timestamps used in network packets use an 48 bit (i.e. 6 bytes) only + * seconds fields, so a conversion is required whenever such a seconds field + * is to be read or written. + * + * In the PTP specs this is referenced as @a UInteger48. + * + * This is defined as a structure with an array member to avoid + * potential problems when passing the address as a reference, + * e.g. sizeof( *p ). + * + * @see ::PTP_PKT_TSTAMP + */ +typedef struct +{ + uint8_t b[6]; + +} PTP_PKT_TSTAMP_SECS; + + + +/** + * @brief PTP packet timestamp nanoseconds field. + * + * @see ::PTP_PKT_TSTAMP + */ +typedef uint32_t PTP_PKT_TSTAMP_NSECS; + + + +/** + * @brief PTP packet timestamp. + */ +typedef struct +{ + PTP_PKT_TSTAMP_SECS secs; + PTP_PKT_TSTAMP_NSECS nsecs; + +} PTP_PKT_TSTAMP; + + + +/** + * @brief Data type to store daylight saving flags in TLVs. + * + * @see ::PTP_TLV_DST_FLAG_MSKS + */ +typedef uint8_t PTP_TLV_DST_FLAGS; + + + +/** + * @brief Data type to store leap second flags in TLVs. + * + * @see ::PTP_TLV_LS_FLAG_MSKS + */ +typedef uint8_t PTP_TLV_LS_FLAGS; + + + +/** + * @brief Data type to store time offsets of whole seconds in TLVs. + */ +typedef int32_t PTP_TLV_TIME_OFFS; + + + +/** * @brief An enumeration of time scales used with PTP * * @note The standard time scale used by PTP is TAI, which is a linear time scale. @@ -8625,7 +14156,7 @@ typedef struct uint16_t nw_prot; ///< one of the enumerated protocols, see ::PTP_NW_PROTS uint8_t ptp_prot_version; ///< PTP protocol version, 1, or 2, usually 2 for v2 uint8_t port_state; ///< one of the enumerated port states, see ::PTP_PORT_STATES - uint32_t flags; ///< see ::PTP_STATE_FLAGS + uint32_t flags; ///< See ::PTP_STATE_FLAGS NANO_TIME offset; ///< estimated time offset from the upstream time source NANO_TIME path_delay; NANO_TIME mean_path_delay; @@ -8635,14 +14166,14 @@ typedef struct uint16_t clock_offset_scaled_log_variance; uint8_t clock_class; - uint8_t clock_accuracy; ///< see ::PTP_CLOCK_ACCURACIES + uint8_t clock_accuracy; ///< See ::PTP_CLOCK_ACCURACIES - uint32_t reserved_1; ///< reserved, currently always 0 + uint32_t tsu_secs; ///< current seconds value of time stamp unit uint32_t reserved_2; ///< reserved, currently always 0 uint8_t domain_number; ///< the PTP clock domain number, 0:3 - uint8_t time_source; ///< see ::PTP_TIME_SOURCES - uint8_t delay_mech; ///< see ::PTP_DELAY_MECHS + uint8_t time_source; ///< See ::PTP_TIME_SOURCES + uint8_t delay_mech; ///< See ::PTP_DELAY_MECHS int8_t log_delay_req_intv; int16_t utc_offset; ///< %UTC offset observed against TAI @@ -8656,6 +14187,7 @@ typedef struct } PTP_STATE; #define _mbg_swab_ptp_state( _p ) \ +do \ { \ _mbg_swab16( &(_p)->nw_prot ); \ _mbg_swab32( &(_p)->flags ); \ @@ -8665,12 +14197,12 @@ typedef struct _mbg_swab_nano_time( &(_p)->delay_asymmetry ); \ _mbg_swab_ptp_clock_id( &(_p)->gm_id ); \ _mbg_swab16( &(_p)->clock_offset_scaled_log_variance ); \ - _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->tsu_secs ); \ _mbg_swab32( &(_p)->reserved_2 ); \ _mbg_swab16( &(_p)->utc_offset ); \ _mbg_swab_dac_val( &(_p)->osc_dac_cal ); \ _mbg_swab16( &(_p)->reserved_3 ); \ -} +} while ( 0 ) /** @@ -8698,14 +14230,14 @@ enum PTP_STATE_FLAGS */ enum PTP_STATE_FLAG_MASKS { - PTP_FLAG_MSK_SLAVE_ONLY = ( 1UL << PTP_FLAG_SLAVE_ONLY ), ///< see ::PTP_FLAG_SLAVE_ONLY - PTP_FLAG_MSK_IS_SLAVE = ( 1UL << PTP_FLAG_IS_SLAVE ), ///< see ::PTP_FLAG_IS_SLAVE - PTP_FLAG_MSK_TIMESCALE_IS_PTP = ( 1UL << PTP_FLAG_TIMESCALE_IS_PTP ), ///< see ::PTP_FLAG_TIMESCALE_IS_PTP - PTP_FLAG_MSK_LS_ANN = ( 1UL << PTP_FLAG_LS_ANN ), ///< see ::PTP_FLAG_LS_ANN - PTP_FLAG_MSK_LS_ANN_NEG = ( 1UL << PTP_FLAG_LS_ANN_NEG ), ///< see ::PTP_FLAG_LS_ANN_NEG - PTP_FLAG_MSK_IS_UNICAST = ( 1UL << PTP_FLAG_IS_UNICAST ), ///< see ::PTP_FLAG_IS_UNICAST - PTP_FLAG_MSK_UTC_VALID = ( 1UL << PTP_FLAG_UTC_VALID ), ///< see ::PTP_FLAG_UTC_VALID - PTP_FLAG_MSK_ONE_STEP = ( 1UL << PTP_FLAG_ONE_STEP ) ///< see ::PTP_FLAG_ONE_STEP + PTP_FLAG_MSK_SLAVE_ONLY = ( 1UL << PTP_FLAG_SLAVE_ONLY ), ///< See ::PTP_FLAG_SLAVE_ONLY + PTP_FLAG_MSK_IS_SLAVE = ( 1UL << PTP_FLAG_IS_SLAVE ), ///< See ::PTP_FLAG_IS_SLAVE + PTP_FLAG_MSK_TIMESCALE_IS_PTP = ( 1UL << PTP_FLAG_TIMESCALE_IS_PTP ), ///< See ::PTP_FLAG_TIMESCALE_IS_PTP + PTP_FLAG_MSK_LS_ANN = ( 1UL << PTP_FLAG_LS_ANN ), ///< See ::PTP_FLAG_LS_ANN + PTP_FLAG_MSK_LS_ANN_NEG = ( 1UL << PTP_FLAG_LS_ANN_NEG ), ///< See ::PTP_FLAG_LS_ANN_NEG + PTP_FLAG_MSK_IS_UNICAST = ( 1UL << PTP_FLAG_IS_UNICAST ), ///< See ::PTP_FLAG_IS_UNICAST + PTP_FLAG_MSK_UTC_VALID = ( 1UL << PTP_FLAG_UTC_VALID ), ///< See ::PTP_FLAG_UTC_VALID + PTP_FLAG_MSK_ONE_STEP = ( 1UL << PTP_FLAG_ONE_STEP ) ///< See ::PTP_FLAG_ONE_STEP }; @@ -8715,11 +14247,11 @@ enum PTP_STATE_FLAG_MASKS */ typedef struct { - uint16_t nw_prot; ///< see ::PTP_NW_PROTS + uint16_t nw_prot; ///< See ::PTP_NW_PROTS uint8_t selected_presets; ///< selected PTP presets, see ::PTP_PRESETS uint8_t domain_number; ///< the PTP clock domain number, 0:3 - uint8_t delay_mech; ///< see ::PTP_DELAY_MECHS + uint8_t delay_mech; ///< See ::PTP_DELAY_MECHS uint8_t ptp_role; ///< one of the supported PTP roles, see ::PTP_ROLES uint8_t priority_1; ///< priority 1 uint8_t priority_2; ///< priority 2 @@ -8739,22 +14271,26 @@ typedef struct uint32_t upper_bound; ///< sync state set to false if above this limit [ns] uint32_t lower_bound; ///< sync state set to true if below this limit [ns] - uint32_t reserved; ///< reserved, currently always 0 - uint32_t flags; ///< see ::PTP_CFG_FLAG_MASKS + int16_t delay_asymmetry; ///< static delay asymmetry [ns] to be compensated, only supported if + ///< ::PTP_CFG_MSK_HAS_DELAY_ASYMMETRY_CFG is set in ::PTP_CFG_INFO::supp_flags_ex + uint16_t flags_ex; ///< see @ref PTP_CFG_FLAG_EX_MASKS + uint32_t flags; ///< see @ref PTP_CFG_FLAG_MASKS } PTP_CFG_SETTINGS; -#define _mbg_swab_ptp_cfg_settings( _p ) \ -{ \ - _mbg_swab16( &(_p)->nw_prot ); \ - _mbg_swab16( &(_p)->sync_intv ); \ - _mbg_swab16( &(_p)->ann_intv ); \ - _mbg_swab16( &(_p)->delay_req_intv ); \ - _mbg_swab32( &(_p)->upper_bound ); \ - _mbg_swab32( &(_p)->lower_bound ); \ - _mbg_swab32( &(_p)->reserved ); \ - _mbg_swab32( &(_p)->flags ); \ -} +#define _mbg_swab_ptp_cfg_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->nw_prot ); \ + _mbg_swab16( &(_p)->sync_intv ); \ + _mbg_swab16( &(_p)->ann_intv ); \ + _mbg_swab16( &(_p)->delay_req_intv ); \ + _mbg_swab32( &(_p)->upper_bound ); \ + _mbg_swab32( &(_p)->lower_bound ); \ + _mbg_swab16( &(_p)->delay_asymmetry ); \ + _mbg_swab16( &(_p)->flags_ex ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) @@ -8764,7 +14300,7 @@ typedef struct enum PTP_ANN_RCPT_TIMEOUT_LIMITS { PTP_ANN_RCPT_TIMEOUT_MIN = 2, - PTP_ANN_RCPT_TIMEOUT_MAX = 255, + PTP_ANN_RCPT_TIMEOUT_MAX = 8, DEFAULT_PTP_ANN_RCPT_TIMEOUT = 3 }; @@ -8779,7 +14315,7 @@ typedef struct uint8_t ptp_proto_version; ///< PTP protocol version, 1, or 2, usually 2 for v2 uint8_t reserved_1; ///< reserved, currently always 0 - uint16_t reserved_2; ///< reserved, currently always 0 + uint16_t supp_flags_ex; ///< A bit mask of extended supported features, see @ref PTP_CFG_FLAG_EX_MASKS int16_t sync_intv_min; ///< log2 of minimum sync interval [s] int16_t sync_intv_max; ///< log2 of maximum sync interval [s] @@ -8788,7 +14324,7 @@ typedef struct int16_t delay_req_intv_min; ///< log2 of minimum delay request interval [s] int16_t delay_req_intv_max; ///< log2 of maximum delay request interval [s] - uint32_t supp_flags; ///< a bit mask of supported features, see ::PTP_CFG_FLAG_MASKS + uint32_t supp_flags; ///< a bit mask of supported features, see @ref PTP_CFG_FLAG_MASKS uint32_t supp_nw_prot; ///< a bit mask of supported network protocols, see ::PTP_NW_PROT_MASKS uint32_t supp_opt_ext; ///< a bit mask of supported optional extensions, see ::PTP_OPT_EXT_MASKS uint32_t supp_delay_mech; ///< a bit mask of supported delay mechanisms, see ::PTP_DELAY_MECH_MASKS @@ -8796,9 +14332,10 @@ typedef struct } PTP_CFG_INFO; #define _mbg_swab_ptp_cfg_info( _p ) \ +do \ { \ _mbg_swab_ptp_cfg_settings( &(_p)->settings ); \ - _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab16( &(_p)->supp_flags_ex ); \ _mbg_swab16( &(_p)->sync_intv_min ); \ _mbg_swab16( &(_p)->sync_intv_max ); \ _mbg_swab16( &(_p)->ann_intv_min ); \ @@ -8809,7 +14346,7 @@ typedef struct _mbg_swab32( &(_p)->supp_nw_prot ); \ _mbg_swab32( &(_p)->supp_opt_ext ); \ _mbg_swab32( &(_p)->supp_delay_mech ); \ -} +} while ( 0 ) @@ -8833,7 +14370,7 @@ typedef struct * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is not set then the device * definitely supports the multicast slave role. * - * @see ::PTP_CFG_FLAG_MASKS + * @see @ref PTP_CFG_FLAG_MASKS */ enum PTP_CFG_FLAGS { @@ -8855,37 +14392,131 @@ enum PTP_CFG_FLAGS PTP_CFG_ONE_STEP_L2, ///< [R/-] supports the combination of One-Step and Layer2 mode PTP_CFG_ONE_STEP_P2P, ///< [R/-] supports the combination of One-Step and P2P Delay Mechanism + PTP_CFG_TSU_RESET, ///< [R/-] supports TSU reset via register cmd + PTP_CFG_NTP_HW_TS_MASTER, ///< [R/-] supports the NTP HW time stamping in Master mode + PTP_CFG_NTP_HW_TS_SLAVE, ///< [R/-] supports the NTP HW time stamping in Slave mode + PTP_CFG_SYNCE_MASTER, ///< [R/-] Hardware supports Synchronous Ethernet Out + PTP_CFG_SYNCE_SLAVE, ///< [R/-] Hardware supports Synchronous Ethernet In + PTP_CFG_HAS_MUX, ///< [R/-] Hardware supports multiplexed signal outputs + PTP_CFG_CAN_BE_TIME_MONITOR, ///< [R/-] can be Monitoring device for external PTP or NTP devices //### TODO Shouldn't this be an XFEATURE flag? + PTP_CFG_HAS_STATISTICS, ///< [R/-] ::MBG_PTP_STATISTICS_INFO can be queried + + PTP_CFG_CAN_BE_V1_MASTER, ///< [R/-] supports PTPv1 MASTER role + PTP_CFG_CAN_BE_V1_SLAVE, ///< [R/-] supports PTPv1 SLAVE role + PTP_CFG_HAS_V2_COMMON_DATASETS, ///< [R/-] PTPv2 common dataset structures (see IEEE1588-2008, chapter 8.2) can be queried + PTP_CFG_HAS_V1_COMMON_DATASETS, ///< [R/-] PTPv1 common dataset structures can be queried + PTP_CFG_ATOI, ///< [R/-] supports the configurable usage of the Alternate Time Offset Indicator TLV + PTP_CFG_HAS_SMPTE_TLV_STATE, ///< [R/-] SMPTE TLV structure can be queried in slave state + PTP_CFG_NTP_SW_SERVER, ///< [R/W] PTP Module can run as NTP Server in Software mode in parallel to PTP HW time stamp modes + PTP_CFG_HAS_EXT_SUPP_FLAGS, ///< [R/-] PTP Config has extended supp_flags + N_PTP_CFG_FLAGS ///< the number of defined flags }; + /** - * @brief Bit masks used with ::PTP_CFG_INFO::supp_flags and ::PTP_CFG_SETTINGS::flags + * @defgroup group_PTP_CFG_FLAG_MASKS Bit masks used with PTP_CFG_INFO::supp_flags and PTP_CFG_SETTINGS::flags * + * @see ::PTP_CFG_INFO::supp_flags + * @see ::PTP_CFG_SETTINGS::flags * @see ::PTP_CFG_FLAGS + * + * @anchor PTP_CFG_FLAG_MASKS + * + * @{ */ + +#define PTP_CFG_MSK_TIME_SCALE_IS_PTP ( 1UL << PTP_CFG_TIME_SCALE_IS_PTP ) ///< See ::PTP_CFG_TIME_SCALE_IS_PTP +#define PTP_CFG_MSK_V1_HW_COMPAT ( 1UL << PTP_CFG_V1_HW_COMPAT ) ///< See ::PTP_CFG_V1_HW_COMPAT +#define PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE ( 1UL << PTP_CFG_CAN_BE_UNICAST_SLAVE ) ///< See ::PTP_CFG_CAN_BE_UNICAST_SLAVE +#define PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER ( 1UL << PTP_CFG_CAN_BE_MULTICAST_MASTER ) ///< See ::PTP_CFG_CAN_BE_MULTICAST_MASTER +#define PTP_CFG_MSK_CAN_BE_UNICAST_MASTER ( 1UL << PTP_CFG_CAN_BE_UNICAST_MASTER ) ///< See ::PTP_CFG_CAN_BE_UNICAST_MASTER +#define PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO ( 1UL << PTP_CFG_CAN_BE_MULTICAST_AUTO ) ///< See ::PTP_CFG_CAN_BE_MULTICAST_AUTO +#define PTP_CFG_MSK_SUPP_UTC_VALID ( 1UL << PTP_CFG_SUPP_UTC_VALID ) ///< See ::PTP_CFG_SUPP_UTC_VALID +#define PTP_CFG_MSK_CAN_BE_BOTH_MASTER ( 1UL << PTP_CFG_CAN_BE_BOTH_MASTER ) ///< See ::PTP_CFG_CAN_BE_BOTH_MASTER + +#define PTP_CFG_MSK_HYBRID_MASTER ( 1UL << PTP_CFG_HYBRID_MASTER ) ///< See ::PTP_CFG_HYBRID_MASTER +#define PTP_CFG_MSK_HYBRID_SLAVE ( 1UL << PTP_CFG_HYBRID_SLAVE ) ///< See ::PTP_CFG_HYBRID_SLAVE +#define PTP_CFG_MSK_ONE_STEP_MASTER ( 1UL << PTP_CFG_ONE_STEP_MASTER ) ///< See ::PTP_CFG_ONE_STEP_MASTER +#define PTP_CFG_MSK_MNGMNT_MSGS_DISB ( 1UL << PTP_CFG_MNGMNT_MSGS_DISB ) ///< See ::PTP_CFG_MNGMNT_MSGS_DISB +#define PTP_CFG_MSK_SUPP_MCAST_SLAVE_FLAG ( 1UL << PTP_CFG_SUPP_MCAST_SLAVE_FLAG ) ///< See ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG +#define PTP_CFG_MSK_CAN_BE_MULTICAST_SLAVE ( 1UL << PTP_CFG_CAN_BE_MULTICAST_SLAVE ) ///< See ::PTP_CFG_CAN_BE_MULTICAST_SLAVE +#define PTP_CFG_MSK_ONE_STEP_L2 ( 1UL << PTP_CFG_ONE_STEP_L2 ) ///< See ::PTP_CFG_ONE_STEP_L2 +#define PTP_CFG_MSK_ONE_STEP_P2P ( 1UL << PTP_CFG_ONE_STEP_P2P ) ///< See ::PTP_CFG_ONE_STEP_P2P + +#define PTP_CFG_MSK_TSU_RESET ( 1UL << PTP_CFG_TSU_RESET ) ///< See ::PTP_CFG_TSU_RESET +#define PTP_CFG_MSK_NTP_HW_TS_MASTER ( 1UL << PTP_CFG_NTP_HW_TS_MASTER ) ///< See ::PTP_CFG_NTP_HW_TS_MASTER +#define PTP_CFG_MSK_NTP_HW_TS_SLAVE ( 1UL << PTP_CFG_NTP_HW_TS_SLAVE) ///< See ::PTP_CFG_NTP_HW_TS_SLAVE +#define PTP_CFG_MSK_SYNCE_MASTER ( 1UL << PTP_CFG_SYNCE_MASTER ) ///< See ::PTP_CFG_SYNCE_MASTER +#define PTP_CFG_MSK_SYNCE_SLAVE ( 1UL << PTP_CFG_SYNCE_SLAVE ) ///< See ::PTP_CFG_SYNCE_SLAVE +#define PTP_CFG_MSK_HAS_MUX ( 1UL << PTP_CFG_HAS_MUX ) ///< See ::PTP_CFG_HAS_MUX +#define PTP_CFG_MSK_CAN_BE_TIME_MONITOR ( 1UL << PTP_CFG_CAN_BE_TIME_MONITOR ) ///< See ::PTP_CFG_CAN_BE_TIME_MONITOR +#define PTP_CFG_MSK_HAS_STATISTICS ( 1UL << PTP_CFG_HAS_STATISTICS ) ///< See ::PTP_CFG_HAS_STATISTICS + +#define PTP_CFG_MSK_CAN_BE_V1_MASTER ( 1UL << PTP_CFG_CAN_BE_V1_MASTER ) ///< See ::PTP_CFG_CAN_BE_V1_MASTER +#define PTP_CFG_MSK_CAN_BE_V1_SLAVE ( 1UL << PTP_CFG_CAN_BE_V1_SLAVE ) ///< See ::PTP_CFG_CAN_BE_V1_SLAVE +#define PTP_CFG_MSK_HAS_V2_COMMON_DATASETS ( 1UL << PTP_CFG_HAS_V2_COMMON_DATASETS ) ///< See ::PTP_CFG_HAS_V2_COMMON_DATASETS +#define PTP_CFG_MSK_HAS_V1_COMMON_DATASETS ( 1UL << PTP_CFG_HAS_V1_COMMON_DATASETS ) ///< See ::PTP_CFG_HAS_V1_COMMON_DATASETS +#define PTP_CFG_MSK_ATOI ( 1UL << PTP_CFG_ATOI ) ///< See ::PTP_CFG_ATOI +#define PTP_CFG_MSK_HAS_SMPTE_TLV_STATE ( 1UL << PTP_CFG_HAS_SMPTE_TLV_STATE ) ///< See ::PTP_CFG_HAS_SMPTE_TLV_STATE +#define PTP_CFG_MSK_NTP_SW_SERVER ( 1UL << PTP_CFG_NTP_SW_SERVER ) ///< See ::PTP_CFG_NTP_SW_SERVER +#define PTP_CFG_MSK_HAS_EXT_SUPP_FLAGS ( 1UL << PTP_CFG_HAS_EXT_SUPP_FLAGS ) ///< See ::PTP_CFG_CAN_BE_PTP_PROBE + +/** @} defgroup group_PTP_CFG_FLAG_MASKS */ + + + +/** + * @brief Extended flags bits used with PTP configuration + * + * Flags labeled [R/-] can only be used with ::PTP_CFG_INFO::supp_flags + * to indicate that the associated feature is supported in general. + * + * If a flag labeled [R/W] is set in ::PTP_CFG_INFO::supp_flags then + * this flag can also be used with ::PTP_CFG_SETTINGS::flags to control + * the associated feature. + * + * @note Originally, all devices supported the multicast slave role, so + * there was no extra flag to indicate this. However, some newer devices + * may not support the multicast slave role, so two new flags have been + * introduced to cope with this: + * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is set then a different flag + * ::PTP_CFG_CAN_BE_MULTICAST_SLAVE needs to be checked to tell if + * the multicast slave role is supported, or not. + * If ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG is not set then the device + * definitely supports the multicast slave role. + * + * @see @ref PTP_CFG_FLAG_EX_MASKS */ -enum PTP_CFG_FLAG_MASKS +enum PTP_CFG_FLAGS_EX { - PTP_CFG_MSK_TIME_SCALE_IS_PTP = ( 1UL << PTP_CFG_TIME_SCALE_IS_PTP ), ///< see ::PTP_CFG_TIME_SCALE_IS_PTP - PTP_CFG_MSK_V1_HW_COMPAT = ( 1UL << PTP_CFG_V1_HW_COMPAT ), ///< see ::PTP_CFG_V1_HW_COMPAT - PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE = ( 1UL << PTP_CFG_CAN_BE_UNICAST_SLAVE ), ///< see ::PTP_CFG_CAN_BE_UNICAST_SLAVE - PTP_CFG_MSK_CAN_BE_MULTICAST_MASTER = ( 1UL << PTP_CFG_CAN_BE_MULTICAST_MASTER ), ///< see ::PTP_CFG_CAN_BE_MULTICAST_MASTER - PTP_CFG_MSK_CAN_BE_UNICAST_MASTER = ( 1UL << PTP_CFG_CAN_BE_UNICAST_MASTER ), ///< see ::PTP_CFG_CAN_BE_UNICAST_MASTER - PTP_CFG_MSK_CAN_BE_MULTICAST_AUTO = ( 1UL << PTP_CFG_CAN_BE_MULTICAST_AUTO ), ///< see ::PTP_CFG_CAN_BE_MULTICAST_AUTO - PTP_CFG_MSK_SUPP_UTC_VALID = ( 1UL << PTP_CFG_SUPP_UTC_VALID ), ///< see ::PTP_CFG_SUPP_UTC_VALID - PTP_CFG_MSK_CAN_BE_BOTH_MASTER = ( 1UL << PTP_CFG_CAN_BE_BOTH_MASTER ), ///< see ::PTP_CFG_CAN_BE_BOTH_MASTER - - PTP_CFG_MSK_HYBRID_MASTER = ( 1UL << PTP_CFG_HYBRID_MASTER ), ///< see ::PTP_CFG_HYBRID_MASTER - PTP_CFG_MSK_HYBRID_SLAVE = ( 1UL << PTP_CFG_HYBRID_SLAVE ), ///< see ::PTP_CFG_HYBRID_SLAVE - PTP_CFG_MSK_ONE_STEP_MASTER = ( 1UL << PTP_CFG_ONE_STEP_MASTER ), ///< see ::PTP_CFG_ONE_STEP_MASTER - PTP_CFG_MSK_MNGMNT_MSGS_DISB = ( 1UL << PTP_CFG_MNGMNT_MSGS_DISB ), ///< see ::PTP_CFG_MNGMNT_MSGS_DISB - PTP_CFG_MSK_SUPP_MCAST_SLAVE_FLAG = ( 1UL << PTP_CFG_SUPP_MCAST_SLAVE_FLAG ), ///< see ::PTP_CFG_SUPP_MCAST_SLAVE_FLAG - PTP_CFG_MSK_CAN_BE_MULTICAST_SLAVE = ( 1UL << PTP_CFG_CAN_BE_MULTICAST_SLAVE ), ///< see ::PTP_CFG_CAN_BE_MULTICAST_SLAVE - PTP_CFG_MSK_ONE_STEP_L2 = ( 1UL << PTP_CFG_ONE_STEP_L2 ), ///< see ::PTP_CFG_ONE_STEP_L2 - PTP_CFG_MSK_ONE_STEP_P2P = ( 1UL << PTP_CFG_ONE_STEP_P2P ), ///< see ::PTP_CFG_ONE_STEP_P2P + PTP_CFG_CAN_BE_PTP_PROBE, ///< [R/W] PTP can be used in slave mode although not in slave capable slot + PTP_CFG_DISABLE_PTP, ///< [R/W] PTP Port state can be set to DISABLED permanentely + PTP_CFG_HAS_NTP_PKTGEN_IPV6, ///< [R/-] PTP packet generator supports IPv6 + PTP_CFG_HAS_DELAY_ASYMMETRY_CFG,///< [R/-] PTP stack supports configuration of static delay asymmetry to be compensated + N_PTP_CFG_FLAGS_EX }; +/** + * @defgroup group_PTP_CFG_FLAG_EX_MASKS Bit masks used with PTP_CFG_INFO::supp_flags_ex and PTP_CFG_SETTINGS::flags_ex + * + * @see ::PTP_CFG_INFO::supp_flags_ex + * @see ::PTP_CFG_SETTINGS::flags_ex // TODO Is this correct? + * @see ::PTP_CFG_FLAGS_EX + * + * @anchor PTP_CFG_FLAG_EX_MASKS + * + * @{ */ + +#define PTP_CFG_MSK_CAN_BE_PTP_PROBE ( 1UL << PTP_CFG_CAN_BE_PTP_PROBE ) ///< See ::PTP_CFG_CAN_BE_PTP_PROBE +#define PTP_CFG_MSK_DISABLE_PTP ( 1UL << PTP_CFG_DISABLE_PTP ) ///< See ::PTP_CFG_DISABLE_PTP +#define PTP_CFG_MSK_HAS_NTP_PKTGEN_IPV6 ( 1UL << PTP_CFG_HAS_NTP_PKTGEN_IPV6 ) ///< See ::PTP_CFG_HAS_NTP_PKTGEN_IPV6 +#define PTP_CFG_MSK_HAS_DELAY_ASYMMETRY_CFG ( 1UL << PTP_CFG_HAS_DELAY_ASYMMETRY_CFG ) ///< See ::PTP_CFG_HAS_DELAY_ASYMMETRY_CFG + +/** @} defgroup group_PTP_CFG_FLAG_EX_MASKS */ + + /** @brief A bit mask of the unicast role bits within the flag bits */ #define PTP_CFG_MSK_SUPPORT_PTP_UNICAST ( PTP_CFG_MSK_CAN_BE_UNICAST_SLAVE | \ @@ -8894,16 +14525,52 @@ enum PTP_CFG_FLAG_MASKS /** + * @brief Register in TSU-GbE FPGA to determine board features of the current TSU board revision + */ +typedef uint16_t PTP_HW_FEATURES; + + + +/** + * @brief Bits used to define ::PTP_HW_FEAT_MASKS + */ +enum PTP_HW_FEAT_BITS +{ + PTP_FEAT_SYNCE_EXT_MUX, ///< [R] supports SyncE and external signal multiplexer + N_PTP_HW_FEAT ///< the number of defined features +}; + + +// TODO fix comment linkage +/** + * @brief Bit masks used with ::PTP_HW_FEATURES + * + * @see ::PTP_HW_FEAT_BITS + */ +enum PTP_HW_FEAT_MASKS +{ + PTP_HW_FEAT_MSK_SYNCE_EXT_MUX = ( 1UL << PTP_FEAT_SYNCE_EXT_MUX ) ///< See ::PTP_FEAT_SYNCE_EXT_MUX +}; + + + +/** * @brief Known optional PTP protocol extensions, see ::PTP_CFG_SETTINGS::opt_ext * * @see ::PTP_OPT_EXT_MASKS */ enum PTP_OPT_EXTS { - PTP_OPT_EXT_NONE, ///< no extension used - PTP_OPT_EXT_POWER, ///< IEEE C37.238 profile extension - PTP_OPT_EXT_TELECOM, ///< ITU-T G.8265.1 profile extension - N_PTP_OPT_EXT ///< number of known optional extension + PTP_OPT_EXT_NONE, ///< no extension used + PTP_OPT_EXT_POWER, ///< IEEE C37.238-2011 profile extension + PTP_OPT_EXT_TELECOM, ///< ITU-T G.8265.1 profile extension + PTP_OPT_EXT_TELECOM_PHASE, ///< ITU-T G.8275.1 profile extension + PTP_OPT_EXT_SMPTE, ///< SMPTE ST 2059-2 profile extension + PTP_OPT_EXT_8021AS, ///< IEEE 802.1AS profile extension + PTP_OPT_EXT_6185093, ///< IEC/IEEE FDIS 61850-9-3 Power Utility profile extension + PTP_OPT_EXT_TELECOM_PTS, ///< ITU-T G.8275.2 profile extension + PTP_OPT_EXT_C37238_2017, ///< IEEE C37.238-2017 profile extension + N_PTP_OPT_EXT ///< number of known optional extensions }; @@ -8914,9 +14581,15 @@ enum PTP_OPT_EXTS */ enum PTP_OPT_EXT_MASKS { - PTP_MSK_OPT_EXT_NONE = ( 1UL << PTP_OPT_EXT_NONE ), ///< this is actually not used, see ::PTP_OPT_EXT_NONE - PTP_MSK_OPT_EXT_POWER = ( 1UL << PTP_OPT_EXT_POWER ), ///< see ::PTP_OPT_EXT_POWER - PTP_MSK_OPT_EXT_TELECOM = ( 1UL << PTP_OPT_EXT_TELECOM ) ///< see ::PTP_OPT_EXT_TELECOM + PTP_MSK_OPT_EXT_NONE = ( 1UL << PTP_OPT_EXT_NONE ), ///< this is actually not used, see ::PTP_OPT_EXT_NONE + PTP_MSK_OPT_EXT_POWER = ( 1UL << PTP_OPT_EXT_POWER ), ///< See ::PTP_OPT_EXT_POWER + PTP_MSK_OPT_EXT_TELECOM = ( 1UL << PTP_OPT_EXT_TELECOM ), ///< See ::PTP_OPT_EXT_TELECOM + PTP_MSK_OPT_EXT_TELECOM_PHASE = ( 1UL << PTP_OPT_EXT_TELECOM_PHASE ), ///< See ::PTP_OPT_EXT_TELECOM_PHASE + PTP_MSK_OPT_EXT_SMPTE = ( 1UL << PTP_OPT_EXT_SMPTE ), ///< See ::PTP_OPT_EXT_SMPTE + PTP_MSK_OPT_EXT_8021AS = ( 1UL << PTP_OPT_EXT_8021AS ), ///< See ::PTP_OPT_EXT_8021AS + PTP_MSK_OPT_EXT_6185093 = ( 1UL << PTP_OPT_EXT_6185093 ), ///< See ::PTP_OPT_EXT_6185093 + PTP_MSK_OPT_EXT_TELECOM_PTS = ( 1UL << PTP_OPT_EXT_TELECOM_PTS ), ///< See ::PTP_OPT_EXT_TELECOM_PTS + PTP_MSK_OPT_EXT_C37238_2017 = ( 1UL << PTP_OPT_EXT_C37238_2017 ) ///< See ::PTP_MSK_OPT_EXT_C37238_2017 }; @@ -8932,12 +14605,20 @@ enum PTP_OPT_EXT_MASKS */ enum PTP_PRESETS { - PTP_PRESETS_CUSTOM, ///< customizable, always supported - PTP_PRESETS_DFLT_E2E, ///< pure IEEE1588-2008 (PTPv2) with E2E - PTP_PRESETS_DFLT_P2P, ///< pure IEEE1588-2008 (PTPv2) with P2P - PTP_PRESETS_POWER, ///< IEEE C37.238 profile extension, only if ::PTP_MSK_OPT_EXT_POWER is set - PTP_PRESETS_TELECOM, ///< ITU-T G.8265.1 profile extension, only if ::PTP_MSK_OPT_EXT_TELECOM is set - N_PTP_PRESETS ///< number of supported profiles + PTP_PRESETS_CUSTOM, ///< customizable, always supported + PTP_PRESETS_DFLT_E2E, ///< pure IEEE1588-2008 (PTPv2) with E2E + PTP_PRESETS_DFLT_P2P, ///< pure IEEE1588-2008 (PTPv2) with P2P + PTP_PRESETS_POWER, ///< IEEE C37.238 profile extension, only if ::PTP_MSK_OPT_EXT_POWER is set + PTP_PRESETS_TELECOM, ///< ITU-T G.8265.1 profile extension, only if ::PTP_MSK_OPT_EXT_TELECOM is set + PTP_PRESETS_TELECOM_PHASE, ///< ITU-T G.8275.1 profile extension, only if ::PTP_MSK_OPT_EXT_TELECOM_PHASE is set + PTP_PRESETS_SMPTE, ///< SMPTE ST 2059-2 profile extension, only if ::PTP_MSK_OPT_EXT_SMPTE is set + PTP_PRESETS_AES67, ///< AES67 media profile + PTP_PRESETS_8021AS, ///< IEEE 802.1AS -like profile, only if ::PTP_MSK_OPT_EXT_8021AS is set + PTP_PRESETS_6185093, ///< IEC/IEEE FDIS 61850-9-3, only if ::PTP_MSK_OPT_EXT_6185093 is set + PTP_PRESETS_TELECOM_PTS, ///< ITU-T G.8275.2 profile extension, only if ::PTP_MSK_OPT_EXT_TELECOM_PTS is set + PTP_PRESETS_DOCSIS_31, ///< only if ::PTP_MSK_OPT_EXT_TELECOM_PHASE is set + PTP_PRESETS_C37238_2017, ///< only if ::PTP_MSK_OPT_EXT_C37238_2017 is set + N_PTP_PRESETS ///< number of supported presets }; @@ -8948,11 +14629,20 @@ enum PTP_PRESETS */ enum PTP_PRESETS_MASKS { - PTP_MSK_PRESETS_CUSTOM = ( 1UL << PTP_PRESETS_CUSTOM ), ///< see ::PTP_PRESETS_CUSTOM - PTP_MSK_PRESETS_DFLT_E2E = ( 1UL << PTP_PRESETS_DFLT_E2E ), ///< see ::PTP_PRESETS_DFLT_E2E - PTP_MSK_PRESETS_DFLT_P2P = ( 1UL << PTP_PRESETS_DFLT_P2P ), ///< see ::PTP_PRESETS_DFLT_P2P - PTP_MSK_PRESETS_POWER = ( 1UL << PTP_PRESETS_POWER ), ///< see ::PTP_PRESETS_POWER - PTP_MSK_PRESETS_TELECOM = ( 1UL << PTP_PRESETS_TELECOM ) ///< see ::PTP_PRESETS_TELECOM + PTP_MSK_PRESETS_CUSTOM = ( 1UL << PTP_PRESETS_CUSTOM ), ///< See ::PTP_PRESETS_CUSTOM + PTP_MSK_PRESETS_DFLT_E2E = ( 1UL << PTP_PRESETS_DFLT_E2E ), ///< See ::PTP_PRESETS_DFLT_E2E + PTP_MSK_PRESETS_DFLT_P2P = ( 1UL << PTP_PRESETS_DFLT_P2P ), ///< See ::PTP_PRESETS_DFLT_P2P + PTP_MSK_PRESETS_POWER = ( 1UL << PTP_PRESETS_POWER ), ///< See ::PTP_PRESETS_POWER + PTP_MSK_PRESETS_TELECOM = ( 1UL << PTP_PRESETS_TELECOM ), ///< See ::PTP_PRESETS_TELECOM + PTP_MSK_PRESETS_TELECOM_PHASE = ( 1UL << PTP_PRESETS_TELECOM_PHASE ), ///< See ::PTP_PRESETS_TELECOM_PHASE + PTP_MSK_PRESETS_SMPTE = ( 1UL << PTP_PRESETS_SMPTE ), ///< See ::PTP_PRESETS_SMPTE + PTP_MSK_PRESETS_AES67 = ( 1UL << PTP_PRESETS_AES67 ), ///< See ::PTP_PRESETS_AES67 + PTP_MSK_PRESETS_8021AS = ( 1UL << PTP_PRESETS_8021AS ), ///< See ::PTP_PRESETS_8021AS + PTP_MSK_PRESETS_6185093 = ( 1UL << PTP_PRESETS_6185093), ///< See ::PTP_PRESETS_6185093 + PTP_MSK_PRESETS_TELECOM_PTS = ( 1UL << PTP_PRESETS_TELECOM_PTS), ///< See ::PTP_PRESETS_TELECOM_PTS + PTP_MSK_PRESETS_DOCSIS_31 = ( 1UL << PTP_PRESETS_DOCSIS_31), ///< See ::PTP_PRESETS_DOCSIS_31 + PTP_MSK_PRESETS_C37238_2017 = ( 1UL << PTP_PRESETS_C37238_2017) ///< See ::PTP_PRESETS_C37238_2017 + }; @@ -8961,13 +14651,21 @@ enum PTP_PRESETS_MASKS * * @see ::PTP_PRESETS */ -#define PTP_PRESETS_STRS \ -{ \ - "Custom", \ - "Default E2E", \ - "Default P2P", \ - "Power", \ - "Telecom" \ +#define PTP_PRESETS_STRS \ +{ \ + "Custom", \ + "Default E2E IEEE1588-2008", \ + "Default P2P IEEE1588-2008", \ + "Power IEEE C37.238-2011", \ + "Telecom ITU-T G.8265.1", \ + "Telecom ITU-T G.8275.1", \ + "SMPTE ST 2059-2", \ + "AES67 Media", \ + "IEEE 802.1AS", \ + "Utility IEC 61850-9-3", \ + "Telecom ITU-T G.8275.2", \ + "DOCSIS 3.1", \ + "Power IEEE C37.238-2017" \ } @@ -8983,22 +14681,525 @@ typedef struct uint32_t network_incaccuracy; ///< Pre-defined network inaccuracy from master in [ns] uint8_t grandmaster_id; ///< [::PTP_POWER_PROFILE_GM_ID_MIN..::PTP_POWER_PROFILE_GM_ID_MAX] uint8_t reserved_1; - uint16_t reserved_2; + uint16_t grandmaster_id_2017; ///< Grandmaster ID defined in C.37.2017 is now 16 Bits TZDL tzdl; } PTP_POWER_PROFILE_CFG; #define _mbg_swab_ptp_power_profile_cfg( _p ) \ +do \ { \ _mbg_swab32( &(_p)->network_incaccuracy ); \ _mbg_swab8( &(_p)->grandmaster_id ); \ _mbg_swab8( &(_p)->reserved_1 ); \ - _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab16( &(_p)->grandmaster_id_2017 ); \ _mbg_swab_tzdl( &(_p)->tzdl ); \ _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +#if defined( _PRELIMINARY_CODE ) + +// TODO: These definitions are preliminary and maybe subject to changes. + +/** + * @brief SMPTE System Frame Rates according to SMPTE ST 2059-2 + * + * @see ::TODO + */ +enum SMPTE_SYSTEM_FRAME_RATES +{ + SMPTE_23_98HZ, + SMPTE_24HZ, + SMPTE_25HZ, + SMPTE_29_97HZ, + SMPTE_50HZ, + SMPTE_59_94HZ, + N_SMPTE_SYSTEM_FRAME_RATES +}; + + +#define SMPTE_SYSTEM_FRAME_RATE_STR \ +{ \ + "24Hz (23.98)", \ + "24Hz", \ + "25Hz", \ + "30Hz (29.97)", \ + "50Hz", \ + "60Hz (59.94)" \ +} + + +#define SMPTE_FRAME_RATE_NUM \ +{ \ + 24000, \ + 24000, \ + 25000, \ + 30000, \ + 50000, \ + 60000, \ +} + +#define SMPTE_FRAME_RATE_DENUM \ +{ \ + 1001, \ + 1000, \ + 1000, \ + 1001, \ + 1000, \ + 1001, \ +} + + +/** + * @brief Additional parameters for SMPTE ST 2059-2 profile + * + * This stucture holds the synchronization metadata required for the SMPTE profile. + * This structure is only used for internal storage of the data. The data is + * distributed through a network by using management messages and the dedicated + * organization extension TLV defined in the SMPTE profile. + */ +typedef struct +{ + /// @brief Default system frame rate. + /// + /// Default video frame rate of the slave system as a lowest term rational. + /// The data type shall be composed of a pair of unsigned Int32 values coded + /// in big-endian form where the first shall be the numerator and the second + /// shall be the denominator. The denominator shall be the smallest value + /// that represents the frame rate denominator + /// For example, 29.97 Hz: (30000/1001) or 25 Hz: (25/1). + uint32_t defaultSystemFrameRateNum; + + /// @brief The denominator associated with @a #defaultSystemFrameRateNum. + uint32_t defaultSystemFrameRateDenum; + + /// @brief Master locking status + /// + /// Complementary information to clockClass (0: Not in use, 1: Free Run, + /// 2: Cold Locking, 3: Warm Locking, 4: Locked) + uint8_t masterLockingStatus; + + /// @brief Time Address Flags + /// + /// Indicates the intended ST 12-1 flags. + /// Bit 0: Drop frame (0: Non-drop-frame, 1: Drop-frame) + /// Bit 1: Color Frame Identification (0: Not in use, 1: In use) + /// Bits 2-7: Reserved + uint8_t timeAddressFlags; + + uint8_t reserved_1; + uint8_t reserved_2; + + /// @brief Current local offset. + /// + /// Offset in seconds of Local Time from grandmaster PTP time. For example, + /// if Local Time is Eastern Standard Time (North America) %UTC-5 and the + /// number of leap seconds is 35, the value will be -18035 (decimal). + int32_t currentLocalOffset; + + /// @brief Jump seconds. + /// + /// The size of the next discontinuity, in seconds, of Local Time. A value + /// of zero indicates that no discontinuity is expected. A positive value + /// indicates that the discontinuity will cause @a #currentLocalOffset to increase. + int32_t jumpSeconds; + + /// @brief Time of next jump. + /// + /// The value of the seconds portion of the grandmaster PTP time at the time + /// that the next discontinuity of the @a #currentLocalOffset will occur. The + /// discontinuity occurs at the start of the second indicated. + PTP_PKT_TSTAMP_SECS timeOfNextJump; + + /// @brief Time of next jam. + /// + /// The value of the seconds portion of the PTP time corresponding to the next + /// scheduled occurrence of the Daily Jam. If no Daily Jam is scheduled, the + /// value of @a #timeOfNextJam shall be zero. + PTP_PKT_TSTAMP_SECS timeOfNextJam; + + /// @brief Time of previous jam. + /// + /// The value of the seconds portion of the PTP time corresponding to the + /// previous occurrence of the Daily Jam. + PTP_PKT_TSTAMP_SECS timeOfPreviousJam; + + uint8_t reserved_3; + uint8_t reserved_4; + uint32_t reserved_5; + + /// @brief Previous jam local offset. + /// + /// The value of @a #currentLocalOffset at the previous daily jam time. + /// If a discontinuity of Local Time occurs at the jam time, this parameter + /// reflects the offset after the discontinuity. + PTP_TLV_TIME_OFFS previousJamLocalOffset; + + PTP_TLV_DST_FLAGS daylightSaving; ///< Daylight saving flags, see ::PTP_TLV_DST_FLAG_MSKS. + + PTP_TLV_LS_FLAGS leapSecondJump; ///< Leap second flags, see ::PTP_TLV_LS_FLAG_MSKS. + + uint8_t reserved_6; + uint8_t reserved_7; + + uint32_t reserved_8; + uint32_t reserved_9; + uint32_t reserved_10; + +} PTP_SMPTE_PROFILE_CFG; + +#define _mbg_swab_ptp_smpte_profile_cfg( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->defaultSystemFrameRateNum ); \ + _mbg_swab32( &(_p)->defaultSystemFrameRateDenum ); \ + _mbg_swab32( &(_p)->currentLocalOffset ); \ + _mbg_swab32( &(_p)->jumpSeconds ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ + _mbg_swab32( &(_p)->previousJamLocalOffset ); \ + _mbg_swab32( &(_p)->reserved_8 ); \ + _mbg_swab32( &(_p)->reserved_8 ); \ + _mbg_swab32( &(_p)->reserved_9 ); \ + _mbg_swab32( &(_p)->reserved_10 ); \ +} while ( 0 ) + + + +/** + * @brief Additional parameters for Telecom8275.1 profile + */ +typedef struct +{ + uint8_t use_alternate_multicast_address; + uint8_t reserved_1; + uint8_t reserved_2; + uint8_t reserved_3; + uint32_t reserved_4; + +} PTP_TELECOMG8275_PROFILE_CFG; + +#define _mbg_swab_ptp_telecom8275_profile_cfg( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->use_alternate_multicast_mac_address ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab8( &(_p)->reserved_2 ); \ + _mbg_swab8( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ +} while ( 0 ) + + + +/** + * @brief A type which holds one of the ITU-T SSM codes + * + * @see ::ITU_SSM_CODES + */ +typedef uint16_t ITU_SSM_CODE; + + + +/** + * @brief ITU-T SSM codes acc. to Recommendation G.781 + * + * @see ::ITU_SSM_CODE + */ +enum ITU_SSM_CODES +{ + ITU_SSM_CODE_STU_UKN, + ITU_SSM_CODE_PRS, + ITU_SSM_CODE_PRC, + ITU_SSM_CODE_INV3, + ITU_SSM_CODE_SSU_A_TNC, + ITU_SSM_CODE_INV5, + ITU_SSM_CODE_INV6, + ITU_SSM_CODE_ST2, + ITU_SSM_CODE_SSU_B, + ITU_SSM_CODE_INV9, + ITU_SSM_CODE_ST3, + ITU_SSM_CODE_SEC, + ITU_SSM_CODE_SMC, + ITU_SSM_CODE_ST3E, + ITU_SSM_CODE_PROV, + ITU_SSM_CODE_DNU_DUS, + N_ITU_SSM_CODES +}; + + +#define N_SSM_CODES_OPTION_1 5 +#define N_SSM_CODES_OPTION_2 9 + + +/** + * @brief Name strings for SSM codes, network option I + * + * @see ::ITU_SSM_CODES + */ +#define ITU_SSM_CODE_OPT_1_STRS \ +{ \ + "", \ + "", \ + "QL-PRC", \ + "", \ + "QL-SSU-A", \ + "", \ + "", \ + "", \ + "QL-SSU-B", \ + "", \ + "", \ + "QL-SEC", \ + "", \ + "", \ + "", \ + "QL-DNU" \ +} + + + +/** + * @brief Name strings for SSM codes, network option II + * + * @see ::ITU_SSM_CODES + */ +#define ITU_SSM_CODE_OPT_2_STRS \ +{ \ + "QL-STU", \ + "QL-PRS", \ + "", \ + "", \ + "QL-TNC", \ + "", \ + "", \ + "QL-ST2", \ + "", \ + "", \ + "QL-ST3", \ + "", \ + "QL-SMC", \ + "QL-ST3E", \ + "QL-PROV", \ + "QL-DUS" \ +} + + + +/** + * @brief Name strings for SSM codes, option I and II combined + * + * @see ::ITU_SSM_CODES + */ +#define ITU_SSM_CODE_STRS_COMBINED \ +{ \ + "QL-STU/UKN", \ + "QL-PRS", \ + "QL-PRC", \ + "QL-INV3", \ + "QL-SSU-A/TNC", \ + "QL-INV5", \ + "QL-INV6", \ + "QL-ST2", \ + "QL-SSU-B", \ + "QL-INV9", \ + "QL-EEC2/ST3", \ + "QL-EEC1/SEC", \ + "QL-SMC", \ + "QL-ST3E", \ + "QL-PROV", \ + "QL-DNU/DUS", \ +} + + + +/** + * @brief Maximum T1 SSM only quality levels + * + * @see ::T1_SSM_QLVL + * @see ::T1_SSM_QLVL_STRS + * @see ::T1_SSM_QLVL_ARRAY + */ +#define MAX_T1_SSM_QLVL 8 + + + +/** + * @brief T1 SSM only quality level (6 bit encoded) + * + * @see ::MAX_T1_SSM_QLVL + * @see ::T1_SSM_QLVL_STRS + * @see ::T1_SSM_QLVL_ARRAY + */ +enum T1_SSM_QLVL +{ + T1_SSM_QLVL_ST1_TRACE = 2, + T1_SSM_QLVL_SYNC_TRACE_UNKNOWN = 4, + T1_SSM_QLVL_ST2_TRACE = 6, + T1_SSM_QLVL_ST3_TRACE = 8, + T1_SSM_QLVL_SONET_MIN_CLOCK_TRACE = 17, + T1_SSM_QLVL_ST4_TRACE = 20, + T1_SSM_QLVL_DNU_FOR_SYNC = 24, + T1_SSM_QLVL_RESERVED = 32 +}; + + + +/** + * @brief T1 SSM only quality level array + * + * @see ::MAX_T1_SSM_QLVL + * @see ::T1_SSM_QLVL_STRS + * @see ::T1_SSM_QLVL + */ +#define T1_SSM_QLVL_ARRAY \ +{ \ + T1_SSM_QLVL_ST1_TRACE, \ + T1_SSM_QLVL_SYNC_TRACE_UNKNOWN, \ + T1_SSM_QLVL_ST2_TRACE, \ + T1_SSM_QLVL_ST3_TRACE, \ + T1_SSM_QLVL_SONET_MIN_CLOCK_TRACE, \ + T1_SSM_QLVL_ST4_TRACE, \ + T1_SSM_QLVL_DNU_FOR_SYNC, \ + T1_SSM_QLVL_RESERVED \ } + +/** + * @brief Name strings for T1 SSM quality levels + * + * @see ::MAX_T1_SSM_QLVL + * @see ::T1_SSM_QLVL + * @see ::T1_SSM_QLVL_ARRAY + */ +#define T1_SSM_QLVL_STRS \ +{ \ + "Stratum 1 traceable", \ + "Synchronized traceability unknown", \ + "Stratum 2 traceable", \ + "Stratum 3 traceable", \ + "SONET minimum clock traceable", \ + "Stratum 4 traceable", \ + "Do not use for sync", \ + "Reserved for network sync" \ +} + + + +/** + * @brief SDH network options + * + * @see ::SDH_NETWORK_OPTION_MASKS + */ +enum SDH_NETWORK_OPTIONS +{ + SDH_NETWORK_OPTION_1, + SDH_NETWORK_OPTION_2, + N_SDH_NETWORK_OPTIONS + +}; + + + +/** + * @brief Flag masks used with :: MBG_NET_INTF_LINK_INFO::supp_sdh_net_opts + * + * @see ::SDH_NETWORK_OPTIONS + */ +enum SDH_NETWORK_OPTION_MASKS +{ + SDH_NETWORK_OPTION_1_MSK = ( 1UL << SDH_NETWORK_OPTION_1 ), ///< See ::SDH_NETWORK_OPTION_1 + SDH_NETWORK_OPTION_2_MSK = ( 1UL << SDH_NETWORK_OPTION_2 ), ///< See ::SDH_NETWORK_OPTION_2 +}; + + + +/** + * @brief Name strings for SDH network options + * + * @see ::SDH_NETWORK_OPTIONS + */ +#define SDH_NETWORK_OPTION_STRS \ +{ \ + "SDH Network Opt. 1", \ + "SDH Network Opt. 2", \ +} + + +/** + * @brief Link modes for SyncE on a 1000BASE-T interface. + * + * @see ::GBIT_LINK_COPPER_MODE_MASKS + */ +enum GBIT_LINK_COPPER_MODES +{ + GBIT_LINK_COPPER_AUTO, // valid if synce is disabled + GBIT_LINK_COPPER_FORCE_SYNCE_AUTO, + GBIT_LINK_COPPER_FORCE_OR_IS_MASTER, // Used in both structures, settings and status + GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE, // Used in both structures, settings and status + GBIT_LINK_COPPER_PREFER_MASTER, + GBIT_LINK_COPPER_PREFER_SLAVE, + N_GBIT_LINK_COPPER_MODES +}; + + + +/** + * @brief Flag masks used with ::MBG_NET_INTF_LINK_INFO::supp_gb_copper_modes. + * + * @see ::GBIT_LINK_COPPER_MODES + */ +enum GBIT_LINK_COPPER_MODE_MASKS +{ + GBIT_LINK_COPPER_AUTO_MSK = ( 1UL << GBIT_LINK_COPPER_AUTO ), ///< See ::GBIT_LINK_COPPER_AUTO_MSK + GBIT_LINK_COPPER_FORCE_SYNCE_AUTO_MSK = ( 1UL << GBIT_LINK_COPPER_FORCE_SYNCE_AUTO ), ///< See ::GBIT_LINK_COPPER_FORCE_SYNCE_AUTO + GBIT_LINK_COPPER_FORCE_OR_IS_MASTER_MSK = ( 1UL << GBIT_LINK_COPPER_FORCE_OR_IS_MASTER ), ///< See ::GBIT_LINK_COPPER_FORCE_OR_IS_MASTER + GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE_MSK = ( 1UL << GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE ), ///< See ::GBIT_LINK_COPPER_FORCE_OR_IS_SLAVE + GBIT_LINK_COPPER_PREFER_MASTER_MSK = ( 1UL << GBIT_LINK_COPPER_PREFER_MASTER ), ///< See ::GBIT_LINK_COPPER_PREFER_MASTER + GBIT_LINK_COPPER_PREFER_SLAVE_MSK = ( 1UL << GBIT_LINK_COPPER_PREFER_SLAVE ) ///< See ::GBIT_LINK_COPPER_PREFER_SLAVE +}; + + + +//##++++ TODO: shouldn't this be merged with MBG_NET_LINK_ROLE_BITS / MBG_NET_LINK_ROLE_MASKS? +/** + * @brief Link status for SyncE on a 1000BASE-T interface + * + * @see ::TODO + */ +enum GBIT_LINK_STATUS +{ + GBIT_LINK_COPPER_IS_MASTER, ///< GBIT Link is currently clock master + GBIT_LINK_COPPER_IS_SLAVE, ///< GBIT Link is currently clock slave + GBIT_LINK_COPPER_CFG_FAULT, ///< GBIT Link has a configruation fault (conflict with link partner + GBIT_LINK_COPPER_IS_FE, ///< Link is running on Fast Ethernet (no MASTER/SLAVE decision) + GBIT_LINK_DOWN, ///< Currently no link + GBIT_LINK_FIBER, ///< GBIT Linkup on SFP interface + N_GBIT_LINK_STATUS +}; + + +#define GBIT_LINK_STATUS_STRS \ +{ \ + "MASTER (1000BASE-T)", \ + "SLAVE (1000BASE-T)", \ + "CFG FAULT", \ + "AUTO (100BASE-TX)", \ + "LINK DOWN", \ + "AUTO (SFP LINK UP)", \ +} + +#else // !defined( _PRELIMINARY_CODE ), dummy declarations + +typedef int PTP_SMPTE_PROFILE_CFG; +typedef int PTP_TELECOMG8275_PROFILE_CFG; +typedef int ITU_SSM_CODE; + +#endif // defined( _PRELIMINARY_CODE ) + + + /** * @brief Limits to be considered when specifying PTP unicast masters */ @@ -9018,6 +15219,7 @@ typedef struct } PTP_UC_MASTER_CFG_LIMITS; #define _mbg_swab_ptp_uc_master_cfg_limits( _p ) \ +do \ { \ _mbg_swab16( &(_p)->n_supp_master ); \ _mbg_swab16( &(_p)->sync_intv_min ); \ @@ -9029,7 +15231,8 @@ typedef struct _mbg_swab16( &(_p)->reserved_0 ); \ _mbg_swab32( &(_p)->supp_flags ); \ _mbg_swab32( &(_p)->reserved_1 ); \ -} +} while ( 0 ) + /** @@ -9045,21 +15248,22 @@ typedef struct */ typedef struct { - MBG_HOSTNAME gm_host; ///< grandmaster's hostname or IP address - PTP_CLOCK_ID gm_clock_id; ///< use clock ID of master port, or ::PTP_CLOCK_ID_WILDCARD - PTP_PORT_ID gm_port_id; ///< use target port ID of master port (e.g. 135) or ::PTP_PORT_ID_WILDCARD - int16_t sync_intv; ///< sync interval [log2 s] - int16_t ann_intv; ///< announce interval [log2 s] - int16_t delay_req_intv; ///< delay request interval [log2 s] - int32_t fix_offset; ///< constant time offset to be compensated [ns] - uint16_t message_duration; ///< time period until master stops sending messages [s] - uint16_t reserved_0; ///< reserved, currently always 0 - uint32_t reserved_1; ///< reserved, currently always 0 - uint32_t flags; ///< reserved, currently always 0 + MBG_HOSTNAME gm_host; ///< Hostname or IP address of the grandmaster. + PTP_CLOCK_ID gm_clock_id; ///< Clock ID of the master port, or ::PTP_CLOCK_ID_WILDCARD. + PTP_PORT_ID gm_port_id; ///< Target port ID of the master port (e.g. 135) or ::PTP_PORT_ID_WILDCARD. + int16_t sync_intv; ///< Sync interval [log2 s]. + int16_t ann_intv; ///< Announce interval [log2 s]. + int16_t delay_req_intv; ///< Delay request interval [log2 s]. + int32_t fix_offset; ///< Constant time offset to be compensated [ns]. + uint16_t message_duration; ///< Time period until master stops sending messages [s]. + uint16_t reserved_0; ///< Reserved, currently always 0. + uint32_t reserved_1; ///< Reserved, currently always 0. + uint32_t flags; ///< Reserved, currently always 0. } PTP_UC_MASTER_SETTINGS; #define _mbg_swab_ptp_uc_master_settings( _p ) \ +do \ { \ _mbg_swab_ptp_clock_id( &(_p)->gm_clock_id ); \ _mbg_swab_ptp_port_id( &(_p)->gm_port_id ); \ @@ -9071,7 +15275,8 @@ typedef struct _mbg_swab16( &(_p)->reserved_0 ); \ _mbg_swab32( &(_p)->reserved_1 ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) + /** @@ -9098,16 +15303,18 @@ enum PTP_UC_MSG_DURATION_LIMITS */ typedef struct { - uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master-1 + MBG_MSG_IDX_32 idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master-1 PTP_UC_MASTER_SETTINGS settings; ///< specification for the unicast master with that index } PTP_UC_MASTER_SETTINGS_IDX; #define _mbg_swab_ptp_uc_master_settings_idx( _p ) \ +do \ { \ _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ptp_uc_master_settings( &(_p)->settings ); \ -} +} while ( 0 ) + /** @@ -9125,11 +15332,13 @@ typedef struct } PTP_UC_MASTER_INFO; #define _mbg_swab_ptp_uc_master_info( _p ) \ +do \ { \ _mbg_swab_ptp_uc_master_settings( &(_p)->settings ); \ _mbg_swab32( &(_p)->reserved ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) + /** @@ -9147,17 +15356,2626 @@ typedef struct */ typedef struct { - uint32_t idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master-1 + MBG_MSG_IDX_32 idx; ///< index, 0..PTP_UC_MASTER_CFG_LIMITS::n_supp_master-1 PTP_UC_MASTER_INFO info; ///< capabilities and current settings } PTP_UC_MASTER_INFO_IDX; #define _mbg_swab_ptp_uc_master_info_idx( _p ) \ +do \ { \ _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ptp_uc_master_info( &(_p)->info ); \ +} while ( 0 ) + + + +typedef struct +{ + uint32_t counter_cfg; + uint32_t flags; + uint32_t reserved_1; + uint32_t reserved_2; + +} MBG_PTP_STATISTICS_SETTINGS; + + + +typedef struct +{ + MBG_PTP_STATISTICS_SETTINGS settings; + uint32_t supp_flags; ///< Supported settings, currently 0 + uint32_t reserved_1; + +} MBG_PTP_STATISTICS_INFO; + + + +typedef struct +{ + uint32_t status; ///< Status word flags (use PacketCounterStat_e) + uint32_t rx; ///< Overall RX packet counter + uint32_t rxPerSec; ///< Overall RX packet counter + uint32_t tx; ///< Overall TX packet counter + uint32_t txPerSec; ///< Overall TX packet counter + + /// @brief Invalid RX packet counter. + /// + /// Indicates one of the following issues: wrong PTP version, wrong domain number, + /// message from self, message from other BC port, multicast message in unicast mode + /// or message extraction error (size error or inconsistent format). + uint32_t errorRx; + uint32_t announceMsgRx; ///< Accepted Announce message RX counter + uint32_t announceMsgPerSecRx; ///< Accepted Announce message RX counter + uint32_t announceMsgTx; ///< Announce message TX counter + uint32_t announceMsgPerSecTx; ///< Announce message TX counter + uint32_t syncMsgRx; ///< Accepted Sync message RX counter + uint32_t syncMsgPerSecRx; ///< Accepted Sync message RX counter + uint32_t syncMsgTx; ///< Sync message TX counter + uint32_t syncMsgPerSecTx; ///< Sync message TX counter + uint32_t followUpMsgRx; ///< Accepted Follow-up message RX counter + uint32_t followUpMsgPerSecRx; ///< Accepted Follow-up message RX counter + uint32_t followUpMsgTx; ///< Follow-up message TX counter + uint32_t followUpMsgPerSecTx; ///< Follow-up message TX counter + uint32_t dlyReqMsgRx; ///< Accepted Delay request message RX counter + uint32_t dlyReqMsgPerSecRx; ///< Accepted Delay request message RX counter + uint32_t dlyReqMsgTx; ///< Delay request message TX counter + uint32_t dlyReqMsgPerSecTx; ///< Delay request message TX counter + uint32_t dlyRespMsgRx; ///< Accepted Delay response message RX counter + uint32_t dlyRespMsgPerSecRx; ///< Accepted Delay response message RX counter + uint32_t dlyRespMsgTx; ///< Delay response message TX counter + uint32_t dlyRespMsgPerSecTx; ///< Delay response message TX counter + uint32_t pDlyReqMsgRx; ///< Accepted PDelay Request message RX counter + uint32_t pDlyReqMsgPerSecRx; ///< Accepted PDelay Request message RX counter + uint32_t pDlyReqMsgTx; ///< PDelay Request message TX counter + uint32_t pDlyReqMsgPerSecTx; ///< PDelay Request message TX counter + uint32_t pDlyRespMsgRx; ///< Accepted PDelay Response message RX counter + uint32_t pDlyRespMsgPerSecRx; ///< Accepted PDelay Response message RX counter + uint32_t pDlyRespMsgTx; ///< PDelay Response message TX counter + uint32_t pDlyRespMsgPerSecTx; ///< PDelay Response message TX counter + uint32_t pDlyFollowUpRx; ///< Accepted PDelay Follow-Up message RX counter + uint32_t pDlyFollowUpPerSecRx; ///< Accepted PDelay Follow-Up message RX counter + uint32_t pDlyFollowUpTx; ///< PDelay Follow-Up message TX counter + uint32_t pDlyFollowUpPerSecTx; ///< PDelay Follow-Up message TX counter + uint32_t signallingRx; ///< Accepted Signalling message RX counter + uint32_t signallingPerSecRx; ///< Accepted Signalling message RX counter + uint32_t signallingTx; ///< Signalling message TX counter + uint32_t signallingPerSecTx; ///< Signalling message TX counter + uint32_t mgmtRx; ///< Accepted Management message RX counter + uint32_t mgmtPerSecRx; ///< Accepted Management message RX counter + uint32_t mgmtTx; ///< Management message TX counter + uint32_t mgmtPerSecTx; ///< Management message TX counter + uint32_t mgmtErr; ///< Management error counter (RX) + uint32_t annReceptTout; ///< Announce receipt timeout count + + uint32_t numUcConn; ///< Number of current Unicast client connections + uint32_t maxNumUcConn; ///< Maximum Number of Unicast client connections (due to licence or CPU performance) + uint32_t numMsgPerSec; ///< Number of all messages per second (TX/RX) + uint32_t maxMsgPerSec; ///< Max. allowed number of all messages per second in Multicast/Hybrid mode (due to licence or CPU performance) + +} MBG_PTP_STATISTICS_STATUS; + + + +enum PTP_V1_COMM_IDS +{ + V1_PTP_CLOSED, + V1_PTP_ETHER, + /* reserved */ + V1_PTP_FFBUS = 4, + V1_PTP_PROFIBUS, + V1_PTP_LON, + V1_PTP_DNET, + V1_PTP_SDS, + V1_PTP_CONTROLNET, + V1_PTP_CANOPEN, + /* reserved */ + V1_PTP_IEEE1394 = 243, + V1_PTP_IEEE802_11A, + V1_PTP_IEEE_WIRELESS, + V1_PTP_INFINIBAND, + V1_PTP_BLUETOOTH, + V1_PTP_IEEE802_15_1, + V1_PTP_IEEE1451_3, + V1_PTP_IEEE1451_5, + V1_PTP_USB, + V1_PTP_ISA, + V1_PTP_PCI, + V1_PTP_VXI, + V1_PTP_DEFAULT +}; + + + +#define PTP_CODE_STRING_LENGTH 4 +#define PTP_SUBDOMAIN_NAME_LENGTH 16 + + +/** + * @brief PTPv1 UUID structure used in ::MBG_PTP_V1_DEFAULT_DATASET + * + * @see ::MBG_PTP_V1_DEFAULT_DATASET + */ +typedef struct +{ + uint8_t communication_technology; + uint8_t reserved_1; + uint16_t reserved_2; + PTP_CLOCK_ID clock_uuid; + PTP_PORT_ID port_id; + uint16_t reserved_3; + +} PTP_V1_UUID; + + +#define _mbg_swab_ptp_v1_uuid( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab_ptp_clock_id( &(_p)->clock_uuid ); \ + _mbg_swab_ptp_port_id( &(_p)->port_id ); \ + _mbg_swab16( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief PTPv1 default dataset flags + * + * @see ::PTP_V1_DEFAULT_DATASET_FLAGS_MASKS + */ +enum PTP_V1_DEFAULT_DATASET_FLAGS +{ + V1_DFLT_CLK_FOLLOWUP_CAPABLE, + V1_DFLT_PREFERRED, + V1_DFLT_INITIALIZABLE, + V1_DFLT_EXT_TIMING, + V1_DFLT_IS_BC +}; + + + +/** + * @brief PTPv1 default dataset flag masks used with ::MBG_PTP_V1_DEFAULT_DATASET::flags + * + * @see ::PTP_V1_DEFAULT_DATASET_FLAGS + */ +enum PTP_V1_DEFAULT_DATASET_FLAGS_MASKS +{ + V1_DFLT_MSK_CLK_FOLLOWUP_CAPABLE = ( 1UL << V1_DFLT_CLK_FOLLOWUP_CAPABLE ), ///< See ::V1_DFLT_CLK_FOLLOWUP_CAPABLE + V1_DFLT_MSK_PREFERRED = ( 1UL << V1_DFLT_PREFERRED ), ///< See ::V1_DFLT_PREFERRED + V1_DFLT_MSK_INITIALIZABLE = ( 1UL << V1_DFLT_INITIALIZABLE ), ///< See ::V1_DFLT_INITIALIZABLE + V1_DFLT_MSK_EXT_TIMING = ( 1UL << V1_DFLT_EXT_TIMING), ///< See ::V1_DFLT_EXT_TIMING + V1_DFLT_MSK_IS_BC = ( 1UL << V1_DFLT_IS_BC ) ///< See ::V1_DFLT_IS_BC +}; + + +/** + * @brief PTPv1 default dataset containing global information about the device + * + * @see ::PTP_V1_UUID + */ +typedef struct { + PTP_V1_UUID uuid; + uint8_t clock_stratum; + uint8_t clock_identifier[PTP_CODE_STRING_LENGTH]; + uint16_t clock_variance; + int8_t sync_interval; + uint8_t subdomain_name[PTP_SUBDOMAIN_NAME_LENGTH]; + uint16_t number_ports; + uint16_t number_foreign_records; + uint32_t flags; + +} MBG_PTP_V1_DEFAULT_DATASET; + + +#define _mbg_swab_ptp_v1_default_dataset( _p ) \ +do \ +{ \ + _mbg_swab_ptp_v1_uuid( &(_p)->uuid ); \ + _mbg_swab16( &(_p)->clock_variance ); \ + _mbg_swab16( &(_p)->number_ports ); \ + _mbg_swab16( &(_p)->number_foreign_records ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief PTPv1 current dataset containing information about the synchronization status of the device + */ +typedef struct +{ + uint16_t steps_removed; + uint16_t reserved_1; + NANO_TIME offset_from_master; + NANO_TIME one_way_delay; + +} MBG_PTP_V1_CURRENT_DATASET; + + +#define _mbg_swab_ptp_v1_current_dataset( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->steps_removed ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab_nano_time( &(_p)->offset_from_master ); \ + _mbg_swab_nano_time( &(_p)->one_way_delay ); \ +} while ( 0 ) + + + +/** + * @brief PTPv1 parent dataset flags + * + * @see ::PTP_V1_PARENT_DATASET_FLAGS_MASKS + */ +enum PTP_V1_PARENT_DATASET_FLAGS +{ + V1_PARENT_FOLLOWUP_CAPABLE, + V1_PARENT_EXT_TIMING, + V1_PARENT_STATS, + V1_PARENT_UTC_REASONABLE, + V1_PARENT_GM_PREFERRED, + V1_PARENT_GM_IS_BC +}; + + + +/** + * @brief PTPv1 parent dataset flag masks used with ::MBG_PTP_V1_PARENT_DATASET::flags + * + * @see ::PTP_V1_PARENT_DATASET_FLAGS + */ +enum PTP_V1_PARENT_DATASET_FLAGS_MASKS +{ + V1_PARENT_MSK_FOLLOWUP_CAPABLE = ( 1UL << V1_PARENT_FOLLOWUP_CAPABLE ), ///< See ::V1_PARENT_FOLLOWUP_CAPABLE + V1_PARENT_MSK_EXT_TIMING = ( 1UL << V1_PARENT_EXT_TIMING ), ///< See ::V1_PARENT_EXT_TIMING + V1_PARENT_MSK_STATS = ( 1UL << V1_PARENT_STATS ), ///< See ::V1_PARENT_STATS + V1_PARENT_MSK_UTC_REASONABLE = ( 1UL << V1_PARENT_UTC_REASONABLE ), ///< See ::V1_PARENT_UTC_REASONABLE + V1_PARENT_MSK_GM_PREFERRED = ( 1UL << V1_PARENT_GM_PREFERRED ), ///< See ::V1_PARENT_GM_PREFERRED + V1_PARENT_MSK_GM_IS_BC = ( 1UL << V1_PARENT_GM_IS_BC ) ///< See ::V1_PARENT_GM_IS_BC +}; + + + +/** + * @brief PTPv1 parent dataset containing information about the master (parent) of the device + * + * @see ::PTP_V1_UUID + */ +typedef struct +{ + PTP_V1_UUID uuid; + uint16_t parent_last_sync_sequence_number; + int16_t parent_variance; + int16_t observed_variance; + uint16_t reserved_1; + int32_t observed_drift; + PTP_V1_UUID grandmaster_uuid; + uint8_t grandmaster_stratum; + uint8_t grandmaster_identifier[PTP_CODE_STRING_LENGTH]; + int16_t grandmaster_variance; + uint16_t grandmaster_sequence_number; + uint16_t reserved_2; + uint32_t flags; ///< See ::PTP_V1_PARENT_DATASET_FLAGS_MASKS + +} MBG_PTP_V1_PARENT_DATASET; + + +#define _mbg_swab_ptp_v1_parent_dataset( _p ) \ +do \ +{ \ + _mbg_swab_ptp_v1_uuid( &(_p)->uuid ); \ + _mbg_swab16( &(_p)->parent_last_sync_sequence_number ); \ + _mbg_swab16( &(_p)->parent_variance ); \ + _mbg_swab16( &(_p)->observed_variance ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->observed_drift ); \ + _mbg_swab_ptp_v1_uuid( &(_p)->grandmaster_uuid ); \ + _mbg_swab16( &(_p)->grandmaster_variance ); \ + _mbg_swab16( &(_p)->grandmaster_sequence_number ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief PTPv1 time drop dataset flags + * + * @see ::PTP_V1_TIME_PROP_DATASET_FLAGS_MASKS + */ +enum PTP_V1_TIME_PROP_DATASET_DATASET_FLAGS +{ + V1_TPROP_LEAP_59, + V1_TPROP_LEAP_61 +}; + + + +/** + * @brief PTPv1 time drop dataset flag masks used with ::MBG_PTP_V1_TIME_PROPERTIES_DATASET::flags + * + * @see ::PTP_V1_TIME_PROP_DATASET_DATASET_FLAGS + */ +enum PTP_V1_TIME_PROP_DATASET_FLAGS_MASKS +{ + V1_TPROP_MSK_LEAP_59 = ( 1UL << V1_TPROP_LEAP_59 ), ///< See ::V1_TPROP_LEAP_59 + V1_TPROP_MSK_LEAP_61 = ( 1UL << V1_TPROP_LEAP_61 ) ///< See ::V1_TPROP_LEAP_61 +}; + + + +/** + * @brief PTPv1 time drop dataset + * + */ +typedef struct +{ + int16_t current_utc_offset; + uint16_t epoch_number; + uint32_t flags; ///< See ::PTP_V1_TIME_PROP_DATASET_FLAGS_MASKS + +} MBG_PTP_V1_TIME_PROPERTIES_DATASET; + + +#define _mbg_swab_ptp_v1_time_properties_dataset( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->current_utc_offset ); \ + _mbg_swab16( &(_p)->epoch_number ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief PTPv1 port dataset flags + * + * @see ::PTP_V1_PORT_DATASET_FLAGS_MASKS + */ +enum PTP_V1_PORT_DATASET_DATASET_FLAGS +{ + V1_PORT_DATASET_BURST_ENB, +}; + + + +/** + * @brief PTPv1 port dataset flag masks used with ::MBG_PTP_V1_PORT_DATASET::flags + * + * @see ::PTP_V1_PORT_DATASET_DATASET_FLAGS + */ +enum PTP_V1_PORT_DATASET_FLAGS_MASKS +{ + V1_PORT_DATASET_MSK_BURST_ENB = ( 1UL << V1_PORT_DATASET_BURST_ENB ), ///< See ::V1_PORT_DATASET_BURST_ENB +}; + + + +/** + * @brief PTPv1 port dataset containing information about the appropriate port of the device + * + * @see ::PTP_V1_UUID + */ +typedef struct +{ + uint8_t port_state; + uint8_t reserved_1; + uint16_t last_sync_event_sequence_number; + uint16_t last_general_event_sequence_number; + uint16_t reserved_2; + uint32_t subdomain_address; + uint16_t event_port_address; + uint16_t general_port_address; + PTP_V1_UUID uuid; + uint32_t flags; +} MBG_PTP_V1_PORT_DATASET; + + +#define _mbg_swab_ptp_v1_port_dataset( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->last_sync_event_sequence_number ); \ + _mbg_swab16( &(_p)->last_general_event_sequence_number ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->subdomain_address ); \ + _mbg_swab16( &(_p)->event_port_address ); \ + _mbg_swab16( &(_p)->general_port_address ); \ + _mbg_swab_ptp_v1_uuid( &(_p)->uuid ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Index structure for PTPv1 port dataset + * + * @note Port datasets with index 0..::MBG_PTP_V1_DEFAULT_DATASET::number_ports-1 can be queried from a device. + * + * @see ::MBG_PTP_V1_PORT_DATASET + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< Index of the port dataset, 0..::MBG_PTP_V1_DEFAULT_DATASET::number_ports-1. + MBG_PTP_V1_PORT_DATASET port_dataset; ///< See ::MBG_PTP_V1_PORT_DATASET. + +} MBG_PTP_V1_PORT_DATASET_IDX; + + +#define _mbg_swab_ptp_v1_port_dataset_idx( _p ) \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_ptp_v1_port_dataset( &(_p)->port_dataset ); \ +} + + +/** + * @brief Flags structure for the PTPv2 default dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.1 and 15.5.3.3.1 + * + * @see ::MBG_PTP_V2_DEFAULT_DATASET + */ +typedef struct +{ + uint8_t two_step : 1; ///< indicates, whether the clock is a two-step clock + uint8_t slave_only : 1; ///< indicates, whether the clock is a slave-only clock + uint8_t reserved : 6; ///< reserved, currently always 0 + +} MBG_PTP_V2_DEFAULT_DATASET_FLAGS; + +#define _mbg_swab_ptp_v2_default_dataset_flags( _p ) \ + _nop_macro_fnc() + + +/** + * @brief PTPv2 default dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.1 and 15.5.3.3.1 + * + * @see ::MBG_PTP_V2_DEFAULT_DATASET_FLAGS + * @see ::PTP_CLOCK_QUALITY + * @see ::PTP_CLOCK_ID + */ +typedef struct +{ + MBG_PTP_V2_DEFAULT_DATASET_FLAGS flags; ///< flags field, see ::MBG_PTP_V2_DEFAULT_DATASET_FLAGS + uint8_t reserved_1; ///< reserved, currently always 0 + uint16_t number_ports; ///< number of PTP ports on the device + uint8_t priority_1; ///< priority 1 attribute for the local clock + PTP_CLOCK_QUALITY clock_quality; ///< quality of the local clock, see ::PTP_CLOCK_QUALITY + uint8_t priority_2; ///< priority 2 attribute for the local clock + PTP_CLOCK_ID clock_identity; ///< identity of the local clock, see ::PTP_CLOCK_ID + uint8_t domain_number; ///< domain attribute of the local clock + uint8_t reserved_2; ///< reserved, currently always 0 + +} MBG_PTP_V2_DEFAULT_DATASET; + + +#define _mbg_swab_ptp_v2_default_dataset( _p ) \ +{ \ + _mbg_swab_ptp_v2_default_dataset_flags( &(_p)->flags ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->number_ports ); \ + _mbg_swab8( &(_p)->priority_1 ); \ + _mbg_swab_ptp_clock_quality( &(_p)->clock_quality ); \ + _mbg_swab8( &(_p)->priority_2 ); \ + _mbg_swab_ptp_clock_id( &(_p)->clock_identity ); \ + _mbg_swab8( &(_p)->domain_number ); \ + _mbg_swab8( &(_p)->reserved_2 ); \ +} + + +/** + * @brief Flags for the PTPv2 NG default dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.1 and 15.5.3.3.1 + * + * @see ::MBG_PTP_V2_DEFAULT_DATASET + */ +enum MBG_PTP_V2_NG_DFLT_DS_FLAGS +{ + MBG_PTP_V2_NG_DFLT_DS_FLAG_TWO_STEP, + MBG_PTP_V2_NG_DFLT_DS_FLAG_SLAVE_ONLY, + N_MBG_PTP_V2_NG_DFLT_DS_FLAGS + +}; + +enum MBG_PTP_V2_NG_DFLT_DS_FLAG_MASKS +{ + MBG_PTP_V2_NG_DFLT_DS_FLAG_MSK_TWO_STEP = ( 1UL << MBG_PTP_V2_NG_DFLT_DS_FLAG_TWO_STEP), + MBG_PTP_V2_NG_DFLT_DS_FLAG_MSK_SLAVE_ONLY = ( 1UL << MBG_PTP_V2_NG_DFLT_DS_FLAG_SLAVE_ONLY) +}; + +/** + * @brief PTPv2 default dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.1 and 15.5.3.3.1 + * + * @see ::MBG_PTP_V2_DEFAULT_DATASET_FLAGS + * @see ::PTP_CLOCK_QUALITY + * @see ::PTP_CLOCK_ID + */ +typedef struct mbg_ptp_v2_ng_default_dataset_s +{ + uint8_t flags; ///< flags field, see ::MBG_PTP_V2_NG_DFLT_DS_FLAGS + uint8_t reserved_1; ///< reserved, currently always 0 + uint16_t number_ports; ///< number of PTP ports on the device + PTP_CLOCK_QUALITY clock_quality; ///< quality of the local clock, see ::PTP_CLOCK_QUALITY + uint8_t priority_1; ///< priority 1 attribute for the local clock + uint8_t priority_2; ///< priority 2 attribute for the local clock + uint8_t domain_number; ///< domain attribute of the local clock + uint8_t reserved_2; ///< reserved, currently always 0 + uint32_t reserved_3; + PTP_CLOCK_ID clock_identity; ///< identity of the local clock, see ::PTP_CLOCK_ID + +} MBG_PTP_V2_NG_DEFAULT_DATASET; + + +#define _mbg_swab_ptp_v2_ng_default_dataset( _p ) \ +{ \ + _mbg_swab16( &(_p)->number_ports ); \ + _mbg_swab_ptp_clock_quality( &(_p)->clock_quality ); \ + _mbg_swab_ptp_clock_id( &(_p)->clock_identity ); \ +} + + +/** + * @brief PTPv2 current dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.2 and 15.5.3.4.1 + * + * @see ::PTP_TIME_INTERVAL + */ +typedef struct +{ + uint16_t steps_removed; ///< number of communication paths between local clock and grandmaster + PTP_TIME_INTERVAL offset_from_master; ///< current time difference between master and slave, see ::PTP_TIME_INTERVAL + PTP_TIME_INTERVAL mean_path_delay; ///< current mean propagation time between master and slave, see ::PTP_TIME_INTERVAL + +} MBG_PTP_V2_CURRENT_DATASET; + + +#define _mbg_swab_ptp_v2_current_dataset( _p ) \ +{ \ + _mbg_swab16( &(_p)->steps_removed ); \ + _mbg_swab_ptp_time_interval( &(_p)->offset_from_master ); \ + _mbg_swab_ptp_time_interval( &(_p)->mean_path_delay ); \ +} + + + +/** + * @brief PTPv2 current dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.2 and 15.5.3.4.1 + * + * @see ::PTP_TIME_INTERVAL + */ +typedef struct mbg_ptp_v2_ng_current_dataset_s +{ + PTP_TIME_INTERVAL offset_from_master; ///< current time difference between master and slave, see ::PTP_TIME_INTERVAL + PTP_TIME_INTERVAL mean_path_delay; ///< current mean propagation time between master and slave, see ::PTP_TIME_INTERVAL + uint16_t steps_removed; ///< number of communication paths between local clock and grandmaster + uint16_t reserved_1; + uint32_t reserved_2; +} MBG_PTP_V2_NG_CURRENT_DATASET; + + +#define _mbg_swab_ptp_v2_ng_current_dataset( _p ) \ +{ \ + _mbg_swab_ptp_time_interval( &(_p)->offset_from_master ); \ + _mbg_swab_ptp_time_interval( &(_p)->mean_path_delay ); \ + _mbg_swab16( &(_p)->steps_removed ); \ +} + + +/** + * @brief Flags structure for the PTPv2 parent dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.3.3 and 15.5.3.5.1.2 + * + * @see ::MBG_PTP_V2_PARENT_DATASET + */ +typedef struct +{ + uint8_t parent_stats : 1; ///< indicates whether the variance and change rate values are valid + uint8_t reserved : 7; ///< reserved, currently always 0 + +} MBG_PTP_V2_PARENT_DATASET_FLAGS; + +#define _mbg_swab_ptp_v2_parent_dataset_flags( _p )\ + _nop_macro_fnc() + + + +/** + * @brief PTPv2 parent dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.3 and 15.5.3.5.1 + * + * @see ::PTP_PORT_IDENTITY + * @see ::MBG_PTP_V2_PARENT_DATASET_FLAGS + * @see ::PTP_CLOCK_QUALITY + * @see ::PTP_CLOCK_ID + */ +typedef struct +{ + PTP_PORT_IDENTITY parent_port_identity; ///< Identity of the master port, that issues the sync messages, see ::PTP_PORT_IDENTITY + MBG_PTP_V2_PARENT_DATASET_FLAGS flags; ///< Flags field, see ::MBG_PTP_V2_PARENT_DATASET_FLAGS + uint8_t reserved; ///< Reserved, currently always 0 + uint16_t parent_log_variance; ///< Estimate of the PTP variance of the parent clock. Only valid if + ///< ::MBG_PTP_V2_PARENT_DATASET_FLAGS::parent_stats is set in ::MBG_PTP_V2_PARENT_DATASET::flags. + int32_t parent_phase_change_rate; ///< Estimate of the phase change rate of the parent clock. Only valid if + ///< ::MBG_PTP_V2_PARENT_DATASET_FLAGS::parent_stats is set in ::MBG_PTP_V2_PARENT_DATASET::flags. + uint8_t grandmaster_priority_1; ///< Priority 1 attribute of the grandmaster clock. + PTP_CLOCK_QUALITY grandmaster_clock_quality; ///< Quality of the grandmaster clock, see ::PTP_CLOCK_QUALITY. + uint8_t grandmaster_priority_2; ///< Priority 2 attribute of the grandmaster clock. + PTP_CLOCK_ID grandmaster_identity; ///< Identity of the grandmaster clock, see ::PTP_CLOCK_ID. + +} MBG_PTP_V2_PARENT_DATASET; + + +#define _mbg_swab_ptp_v2_parent_dataset( _p ) \ +{ \ + _mbg_swab_ptp_port_identity( &(_p)->parent_port_identity ); \ + _mbg_swab_ptp_v2_parent_dataset_flags( &(_p)->flags ); \ + _mbg_swab8( &(_p)->reserved ); \ + _mbg_swab16( &(_p)->parent_log_variance ); \ + _mbg_swab32( &(_p)->parent_phase_change_rate ); \ + _mbg_swab8( &(_p)->grandmaster_priority_1 ); \ + _mbg_swab_ptp_clock_quality( &(_p)->grandmaster_clock_quality ); \ + _mbg_swab8( &(_p)->grandmaster_priority_2 ); \ + _mbg_swab_ptp_clock_id( &(_p)->grandmaster_identity ); \ +} + + + +/** + * @brief Flags structure for the PTPv2 NG parent dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.3.3 and 15.5.3.5.1.2 + * + * @see ::MBG_PTP_V2_NG_PARENT_DATASET + */ +enum MBG_PTP_V2_NG_PARENT_DATASET_FLAGS +{ + MBG_PTP_V2_NG_PARENT_DS_FLAG_PARENT_STATS, + N_MBG_PTP_V2_NG_PARENT_DS_FLAGS +}; + +enum MBG_PTP_V2_NG_PARENT_DATASET_FLAG_MASKS +{ + MBG_PTP_V2_NG_PARENT_DS_FLAG_MSK_PARENT_STATS = ( 1UL << MBG_PTP_V2_NG_PARENT_DS_FLAG_PARENT_STATS), +}; + +/** + * @brief PTPv2 NG parent dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.3 and 15.5.3.5.1 + * + * @see ::PTP_NG_PORT_IDENTITY + * @see ::MBG_PTP_V2_NG_PARENT_DATASET_FLAGS + * @see ::PTP_CLOCK_QUALITY + * @see ::PTP_CLOCK_ID + */ +typedef struct mbg_ptp_v2_ng_parent_dataset_s +{ + PTP_NG_PORT_IDENTITY parent_port_identity; ///< Identity of the master port, that issues the sync messages, see ::PTP_NG_PORT_IDENTITY. + uint8_t flags; ///< Flags field, see ::MBG_PTP_V2_NG_PARENT_DATASET_FLAGS. + uint8_t reserved_1; ///< Reserved, currently always 0. + uint16_t parent_log_variance; ///< Estimate of the PTP variance of the parent clock, only valid if + ///< ::MBG_PTP_V2_NG_PARENT_DS_FLAG_MSK_PARENT_STATS is set. + int32_t parent_phase_change_rate; ///< Estimate of the phase change rate of the parent clock, only valid if + ///< ::MBG_PTP_V2_NG_PARENT_DS_FLAG_MSK_PARENT_STATS is set. + PTP_CLOCK_QUALITY grandmaster_clock_quality; ///< Quality of the grandmaster clock, see ::PTP_CLOCK_QUALITY. + uint8_t grandmaster_priority_1; ///< Priority 1 attribute of the grandmaster clock. + uint8_t grandmaster_priority_2; ///< Priority 2 attribute of the grandmaster clock. + uint16_t reserved_2; + PTP_CLOCK_ID grandmaster_identity; ///< Identity of the grandmaster clock, see ::PTP_CLOCK_ID. + +} MBG_PTP_V2_NG_PARENT_DATASET; + + +#define _mbg_swab_ptp_v2_ng_parent_dataset( _p ) \ +{ \ + _mbg_swab_ptp_ng_port_identity( &(_p)->parent_port_identity ); \ + _mbg_swab16( &(_p)->parent_log_variance ); \ + _mbg_swab32( &(_p)->parent_phase_change_rate ); \ + _mbg_swab_ptp_clock_quality( &(_p)->grandmaster_clock_quality ); \ + _mbg_swab_ptp_clock_id( &(_p)->grandmaster_identity ); \ +} + + +/** + * @brief Flags structure for the PTPv2 time properties dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.4 and 15.5.3.6.1 + * + * @see ::MBG_PTP_V2_TIME_PROPERTIES_DATASET + */ +typedef struct +{ + uint8_t leap_61 : 1; ///< set, if the last minute of the current %UTC day has 61 seconds + uint8_t leap_59 : 1; ///< set, if the last minute of the current %UTC day has 59 seconds + uint8_t utc_offset_valid : 1; ///< set, if the current %UTC offset is known to be correct + uint8_t ptp_timescale : 1; ///< set, if the timescale of the grandmaster clock is PTP + uint8_t time_traceable : 1; ///< set, if timescale and %UTC offset are traceable to a primary reference + uint8_t frequency_traceable : 1; ///< set, if the frequency determining the timescale is traceable to a primary reference + uint8_t reserved : 2; ///< reserved, currently always 0 + +} MBG_PTP_V2_TIME_PROPERTIES_DATASET_FLAGS; + + +#define _mbg_swab_ptp_v2_time_properties_dataset_flags( _p ) \ + _nop_macro_fnc() + + +/** + * @brief PTPv2 time properties dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.4 and 15.5.3.6.1 + * + * @see ::MBG_PTP_V2_TIME_PROPERTIES_DATASET_FLAGS + */ +typedef struct +{ + int16_t current_utc_offset; ///< offset between TAI and %UTC in seconds + MBG_PTP_V2_TIME_PROPERTIES_DATASET_FLAGS flags; ///< flags field, see ::MBG_PTP_V2_TIME_PROPERTIES_DATASET_FLAGS + uint8_t time_source; ///< source of time used by the grandmaster clock, see ::PTP_TIME_SOURCES + +} MBG_PTP_V2_TIME_PROPERTIES_DATASET; + + +#define _mbg_swab_ptp_v2_time_properties_dataset( _p ) \ +{ \ + _mbg_swab16( &(_p)->current_utc_offset ); \ + _mbg_swab_ptp_v2_time_properties_dataset_flags( &(_p)->flags ); \ + _mbg_swab8( &(_p)->time_source ); \ +} + + +enum MBG_PTP_V2_NG_TIME_PROPERTIES_DATASET_FLAGS +{ + MBG_PTP_V2_NG_TPROP_DS_FLAG_LEAP_61, + MBG_PTP_V2_NG_TPROP_DS_FLAG_LEAP_59, + MBG_PTP_V2_NG_TPROP_DS_FLAG_UTC_OFFSET_VALID, + MBG_PTP_V2_NG_TPROP_DS_FLAG_PTP_TIMESCALE, + MBG_PTP_V2_NG_TPROP_DS_FLAG_TIME_TRACEABLE, + MBG_PTP_V2_NG_TPROP_DS_FLAG_FREQUENCY_TRACEABLE, + N_MBG_PTP_V2_NG_TPROP_DS_FLAGS +}; + +enum MBG_PTP_V2_NG_TIME_PROPERTIES_DATASET_FLAG_MASKS +{ + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_LEAP_61 = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_LEAP_61), + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_LEAP_59 = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_LEAP_59), + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_UTC_OFFSET_VALID = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_UTC_OFFSET_VALID), + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_PTP_TIMESCALE = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_PTP_TIMESCALE), + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_TIME_TRACEABLE = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_TIME_TRACEABLE), + MBG_PTP_V2_NG_TPROP_DS_FLAG_MSK_FREQUENCY_TRACEABLE = ( 1UL << MBG_PTP_V2_NG_TPROP_DS_FLAG_FREQUENCY_TRACEABLE) +}; + + +/** + * @brief PTPv2 time properties dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.4 and 15.5.3.6.1 + * + * @see ::MBG_PTP_V2_TIME_PROPERTIES_DATASET_FLAGS + */ +typedef struct mbg_ptp_v2_ng_time_properties_dataset_s +{ + int16_t current_utc_offset; ///< offset between TAI and %UTC in seconds + uint8_t flags; ///< flags field, see ::MBG_PTP_V2_NG_TIME_PROPERTIES_DATASET_FLAGS + uint8_t time_source; ///< source of time used by the grandmaster clock, see ::PTP_TIME_SOURCES + uint32_t reserved; +} MBG_PTP_V2_NG_TIME_PROPERTIES_DATASET; + + +#define _mbg_swab_ptp_v2_ng_time_properties_dataset( _p ) \ +{ \ + _mbg_swab16( &(_p)->current_utc_offset ); \ +} + + +/** + * @brief PTPv2 port dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.5 and 15.5.3.7.1 + * + * @see ::PTP_PORT_IDENTITY + * @see ::PTP_TIME_INTERVAL + * @see ::MBG_PTP_V2_PORT_DATASET_IDX + */ +typedef struct +{ + PTP_PORT_IDENTITY port_identity; ///< identity of the local port, see ::PTP_PORT_IDENTITY + uint8_t port_state; ///< state of the protocol engine associated with this port, see ::PTP_PORT_STATES + int8_t log_min_delay_req_interval; ///< minimum delay request interval for this port + PTP_TIME_INTERVAL peer_mean_path_delay; ///< estimate of the current one-way propagation delay on the link, only valid if P2P is used, see ::PTP_TIME_INTERVAL + int8_t log_announce_interval; ///< announce interval to be used by this port + uint8_t announce_receipt_timeout; ///< shall be an integral multiple of ::MBG_PTP_V2_PORT_DATASET::log_announce_interval + int8_t log_sync_interval; ///< mean sync interval to be used for multicast messages + uint8_t delay_mechanism; ///< propagation delay measuring option, see ::PTP_DELAY_MECHS + int8_t log_min_pdelay_req_interval; ///< minimum peer delay request interval for this port + uint8_t version_number : 4; ///< PTP version in use on the port + uint8_t reserved : 4; ///< reserved, currently always 0 + +} MBG_PTP_V2_PORT_DATASET; + + +#define _mbg_swab_ptp_v2_port_dataset( _p ) \ +{ \ + _mbg_swab_ptp_port_identity( &(_p)->port_identity ); \ + _mbg_swab8( &(_p)->port_state ); \ + _mbg_swab8( &(_p)->log_min_delay_req_interval ); \ + _mbg_swab_ptp_time_interval( &(_p)->peer_mean_path_delay ); \ + _mbg_swab8( &(_p)->log_announce_interval ); \ + _mbg_swab8( &(_p)->announce_receipt_timeout ); \ + _mbg_swab8( &(_p)->log_sync_interval ); \ + _mbg_swab8( &(_p)->delay_mechanism ); \ + _mbg_swab8( &(_p)->log_min_pdelay_req_interval ); \ +} + + +typedef struct +{ + int8_t ann_intv; + int8_t sync_intv; + int8_t del_req_intv; + int8_t pdel_req_intv; + +} MBG_PTP_NG_INTV_CFG; + + +#define _mbg_swab_ptp_ng_intv_cfg( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->ann_intv ); \ + _mbg_swab8( &(_p)->sync_intv ); \ + _mbg_swab8( &(_p)->del_req_intv ); \ + _mbg_swab8( &(_p)->pdel_req_intv ); \ +} while ( 0 ) + + +/** + * @brief PTPv2 port dataset + * + * @note For further information, see IEEE 1588-2008, chapters 8.2.5 and 15.5.3.7.1 + * + * @see ::PTP_PORT_IDENTITY + * @see ::PTP_TIME_INTERVAL + * @see ::MBG_PTP_V2_PORT_DATASET_IDX + */ +typedef struct mbg_ptp_v2_ng_port_dataset_s +{ + PTP_TIME_INTERVAL peer_mean_path_delay; ///< estimate of the current one-way propagation delay on the link, only valid if P2P is used, see ::PTP_TIME_INTERVAL + PTP_NG_PORT_IDENTITY port_identity; ///< identity of the local port, see ::PTP_PORT_IDENTITY + MBG_PTP_NG_INTV_CFG intvs; ///< interval settings for this port, see ::MBG_PTP_NG_INTV_CFG + uint8_t port_state; ///< state of the protocol engine associated with this port, see ::PTP_PORT_STATES + uint8_t announce_receipt_timeout; ///< shall be an integral multiple of ::MBG_PTP_V2_PORT_DATASET::log_announce_interval + uint8_t delay_mechanism; ///< propagation delay measuring option, see ::PTP_DELAY_MECHS + uint8_t version_number; ///< PTP version in use on the port + +} MBG_PTP_V2_NG_PORT_DATASET; + + +#define _mbg_swab_ptp_v2_ng_port_dataset( _p ) \ +{ \ + _mbg_swab_ptp_time_interval( &(_p)->peer_mean_path_delay ); \ + _mbg_swab_ptp_ng_port_identity( &(_p)->port_identity ); \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs ); \ +} + + +/** + * @brief Index structure for PTPv2 port dataset + * + * @note Port dataset with index 0..::MBG_PTP_V2_DEFAULT_DATASET::number_ports-1 can be queried from a device. + * + * @see ::MBG_PTP_V2_PORT_DATASET + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< Index of the port dataset, 0..::MBG_PTP_V2_DEFAULT_DATASET::number_ports-1. + MBG_PTP_V2_PORT_DATASET port_dataset; ///< See ::MBG_PTP_V2_PORT_DATASET. + +} MBG_PTP_V2_PORT_DATASET_IDX; + + +#define _mbg_swab_ptp_v2_port_dataset_idx( _p ) \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_ptp_v2_port_dataset( &(_p)->port_dataset ); \ +} + +/** + * @brief Index structure for PTPv2 port dataset + * + * @note Port dataset with index 0..::MBG_PTP_V2_DEFAULT_DATASET::number_ports - 1 can be queried from a device + * + * @see ::MBG_PTP_V2_PORT_DATASET + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; ///< Index of the port dataset, 0..::MBG_PTP_V2_DEFAULT_DATASET::number_ports - 1 + uint32_t reserved; + MBG_PTP_V2_NG_PORT_DATASET port_dataset; ///< See ::MBG_PTP_V2_PORT_DATASET + +} MBG_PTP_V2_NG_PORT_DATASET_IDX; + + +/** + * @defgroup group_ptp_ng Next gen structures and definitions used with PTP/IEEE1588 + * + * @{ */ + +typedef char PTP_INTF[MBG_IFNAMSIZ]; ///< interface name (IPv4/L2) or IPv6 address of logical interface linked to this config + + +/** + * @brief PTP version flags + * + * @see ::PTP_NG_VERSION_MASKS + */ +enum PTP_NG_VERSION_FLAGS +{ + PTP_NG_VERSION_1 = 0, + PTP_NG_VERSION_2, + PTP_NG_VERSION_2_1, + N_PTP_NG_VERSIONS +}; + + +/** + * @brief PTP version flag masks used with ::MBG_PTP_NG_GLB_INFO::supp_versions + * + * @see ::PTP_NG_VERSION_FLAGS + */ +enum PTP_NG_VERSION_MASKS +{ + PTP_NG_VERSION_1_MSK = ( 1UL << PTP_NG_VERSION_1 ), ///< See ::PTP_NG_VERSION_1 + PTP_NG_VERSION_2_MSK = ( 1UL << PTP_NG_VERSION_2 ), ///< See ::PTP_NG_VERSION_2 + PTP_NG_VERSION_2_1_MSK = ( 1UL << PTP_NG_VERSION_2_1 ) ///< See ::PTP_NG_VERSION_2_1 +}; + + +#define PTP_NG_VERSION_STRS \ +{ \ + "PTPv1", \ + "PTPv2", \ + "PTPv2.1" \ +} + + +enum MBG_PTP_NG_FLAGS +{ + MBG_PTP_NG_FLAG_ARB_TIMESCALE, ///< Use arbitrary timescale instead of default PTP (TAI) timescale + MBG_PTP_NG_FLAG_V1_HW_COMPATIBILITY, ///< V1 hardware compatibility is used (fill Sync Message with padding bytes) + MBG_PTP_NG_FLAG_BOUNDARY_CLOCK, ///< Indicates, that an instance is part of a boundary clock setup + MBG_PTP_NG_FLAG_SW_TSTAMPING, ///< No hardware timestamps are used + MBG_PTP_NG_FLAG_MANAGEMENT, ///< PTP Management Messages are enabled + MBG_PTP_NG_FLAG_NO_CLK_ADJ, ///< No Adjustment of the hardware clock in slave mode (measurement only) + MBG_PTP_NG_FLAG_PATH_TRACE, ///< Use path trace TLV + MBG_PTP_NG_FLAG_CUSTOM_PORT_ID, ///< A user-defined CLOCK IDENTITY is used for this PTP instance + MBG_PTP_NG_FLAG_FIXED_QUALITY, ///< A user-defined set of fixed BMCA parameters is configured + MBG_PTP_NG_FLAG_AUTHENTICATION, ///< Use authentication as used in PTP v2.1 + MBG_PTP_NG_FLAG_DELAY_ASYMMETRY, ///< Delay asymmetry configuration is supported + MBG_PTP_NG_FLAG_GLB_CLOCK_ID, ///< Use system-wide clock ID for all instances, otherwise use one ID per phys port + MBG_PTP_NG_FLAG_SERVO_SETTINGS, ///< User-defined servo settings, see ::MBG_PTP_NG_SERVO_SETTINGS + MBG_PTP_NG_FLAG_HYBRID_MODE, ///< Use hybrid mode (DelReq. in unicast) + MBG_PTP_NG_FLAG_PKT_CNTRS, ///< Indicates, that an instance supplies packet counters, see ::MBG_PTP_NG_INSTC_PKT_CNTRS + MBG_PTP_NG_FLAG_MIN_GM_CLK_QUALITY, ///< User-defined set of minimum clock quality parameters for synchronization + MBG_PTP_NG_FLAG_DISABLED, ///< Indicates, that an instance is temporarily disabled + N_MBG_PTP_NG_FLAGS +}; + + +enum MBG_PTP_NG_FLAG_MASKS +{ + MBG_PTP_NG_FLAG_ARB_TIMESCALE_MSK = ( 1UL << MBG_PTP_NG_FLAG_ARB_TIMESCALE ), ///< See ::MBG_PTP_NG_FLAG_ARB_TIMESCALE + MBG_PTP_NG_FLAG_V1_HW_COMPATIBILITY_MSK = ( 1UL << MBG_PTP_NG_FLAG_V1_HW_COMPATIBILITY ), ///< See ::MBG_PTP_NG_FLAG_V1_HW_COMPATIBILITY + MBG_PTP_NG_FLAG_BOUNDARY_CLOCK_MSK = ( 1UL << MBG_PTP_NG_FLAG_BOUNDARY_CLOCK ), ///< See ::MBG_PTP_NG_FLAG_BOUNDARY_CLOCK + MBG_PTP_NG_FLAG_SW_TSTAMPING_MSK = ( 1UL << MBG_PTP_NG_FLAG_SW_TSTAMPING ), ///< See ::MBG_PTP_NG_FLAG_SW_TSTAMPING + MBG_PTP_NG_FLAG_MANAGEMENT_MSK = ( 1UL << MBG_PTP_NG_FLAG_MANAGEMENT ), ///< See ::MBG_PTP_NG_FLAG_MANAGEMENT + MBG_PTP_NG_FLAG_NO_CLK_ADJ_MSK = ( 1UL << MBG_PTP_NG_FLAG_NO_CLK_ADJ ), ///< See ::MBG_PTP_NG_FLAG_NO_CLK_ADJ + MBG_PTP_NG_FLAG_PATH_TRACE_MSK = ( 1UL << MBG_PTP_NG_FLAG_PATH_TRACE ), ///< See ::MBG_PTP_NG_FLAG_PATH_TRACE + MBG_PTP_NG_FLAG_CUSTOM_PORT_ID_MSK = ( 1UL << MBG_PTP_NG_FLAG_CUSTOM_PORT_ID ), ///< See ::MBG_PTP_NG_FLAG_CUSTOM_PORT_ID + MBG_PTP_NG_FLAG_FIXED_QUALITY_MSK = ( 1UL << MBG_PTP_NG_FLAG_FIXED_QUALITY ), ///< See ::MBG_PTP_NG_FLAG_FIXED_QUALITY + MBG_PTP_NG_FLAG_AUTHENTICATION_MSK = ( 1UL << MBG_PTP_NG_FLAG_AUTHENTICATION ), ///< See ::MBG_PTP_NG_FLAG_AUTHENTICATION + MBG_PTP_NG_FLAG_DELAY_ASYMMETRY_MSK = ( 1UL << MBG_PTP_NG_FLAG_DELAY_ASYMMETRY ), ///< See ::MBG_PTP_NG_FLAG_DELAY_ASYMMETRY + MBG_PTP_NG_FLAG_GLB_CLOCK_ID_MSK = ( 1UL << MBG_PTP_NG_FLAG_GLB_CLOCK_ID ), ///< See ::MBG_PTP_NG_FLAG_GLB_CLOCK_ID + MBG_PTP_NG_FLAG_SERVO_SETTINGS_MSK = ( 1UL << MBG_PTP_NG_FLAG_SERVO_SETTINGS ), ///< See ::MBG_PTP_NG_FLAG_SERVO_SETTINGS + MBG_PTP_NG_FLAG_HYBRID_MODE_MSK = ( 1UL << MBG_PTP_NG_FLAG_HYBRID_MODE ), ///< See ::MBG_PTP_NG_FLAG_HYBRID_MODE + MBG_PTP_NG_FLAG_PKT_CNTRS_MSK = ( 1UL << MBG_PTP_NG_FLAG_PKT_CNTRS ), ///< See ::MBG_PTP_NG_FLAG_PKT_CNTRS + MBG_PTP_NG_FLAG_MIN_GM_CLK_QUALITY_MSK = ( 1UL << MBG_PTP_NG_FLAG_MIN_GM_CLK_QUALITY ), ///< See ::MBG_PTP_NG_FLAG_MIN_GM_CLK_QUALITY + MBG_PTP_NG_FLAG_DISABLED_MSK = ( 1UL << MBG_PTP_NG_FLAG_DISABLED ) ///< See ::MBG_PTP_NG_FLAG_DISABLED +}; + + +enum MBG_PTP_NG_V1_FLAGS +{ + MBG_PTP_NG_V1_FLAG_PREFERRED, ///< Set preferred flag in PTPv1 stack + MBG_PTP_NG_V1_FLAG_INITIALIZABLE, ///< Set initializable flag in PTPv1 stack + MBG_PTP_NG_V1_FLAG_EXT_TIMING, ///< Set external timing flag in PTPv1 stack + N_MBG_PTP_NG_V1_FLAGS +}; + + +enum MBG_PTP_NG_V1_FLAG_MASKS +{ + MBG_PTP_NG_V1_FLAG_PREFERRED_MSK = ( 1UL << MBG_PTP_NG_V1_FLAG_PREFERRED ), ///< See ::MBG_PTP_NG_V1_FLAG_PREFERRED + MBG_PTP_NG_V1_FLAG_INITIALIZABLE_MSK = ( 1UL << MBG_PTP_NG_V1_FLAG_INITIALIZABLE ), ///< See ::MBG_PTP_NG_V1_FLAG_INITIALIZABLE + MBG_PTP_NG_V1_FLAG_EXT_TIMING_MSK = ( 1UL << MBG_PTP_NG_V1_FLAG_EXT_TIMING ) ///< See ::MBG_PTP_NG_V1_FLAG_EXT_TIMING +}; + + +/** + * @brief Pre-defined alternate time offset indicators + */ +enum MBG_PTP_NG_ATOIS +{ + MBG_PTP_NG_ATOI_UTC, ///< %UTC (Coordinated Universal Time), meaning an almost empty ATOI (minimum requirement for C37.238-2011). + MBG_PTP_NG_ATOI_CUSTOM, ///< Custom, manually configured ATOI stored as ::TZDL structure. + MBG_PTP_NG_ATOI_CET_CEST, ///< CET/CEST (Central European (Summer) Time). + N_MBG_PTP_NG_ATOIS +}; + + +enum MBG_PTP_NG_ATOI_MASKS +{ + MBG_PTP_NG_ATOI_UTC_MSK = ( 1UL << MBG_PTP_NG_ATOI_UTC ), ///< See ::MBG_PTP_NG_ATOI_UTC + MBG_PTP_NG_ATOI_CUSTOM_MSK = ( 1UL << MBG_PTP_NG_ATOI_CUSTOM ), ///< See ::MBG_PTP_NG_ATOI_CUSTOM + MBG_PTP_NG_ATOI_CET_CEST_MSK = ( 1UL << MBG_PTP_NG_ATOI_CET_CEST ) ///< See ::MBG_PTP_NG_ATOI_CET_CEST +}; + + +#define MBG_PTP_NG_ATOI_SHORT_NAMES \ +{ \ + "UTC", \ + "Custom", \ + "CET/CEST" \ +} + + +#define MBG_PTP_NG_ATOI_NAMES \ +{ \ + "UTC (Coordinated Universal Time)", \ + "Custom", \ + "CET/CEST (Central European [Summer] Time)" \ } + + +/** + * @brief Predefined time scales for PTP SMPTE jam event times. + * + * Used with ::MBG_PTP_NG_SMPTE_20592_SETTINGS::event_timescale, + * and to define ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_MASKS. + * + * This is only relevant for the way the ***configuration is stored***, + * and the effective time sent in the SMPTE TLV has to be calculated + * by the appropriate time scale conversion. + * + * @see ::MBG_PTP_NG_SMPTE_20592_SETTINGS::event_timescale + * @see ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_MASKS + */ +enum MBG_PTP_NG_SMPTE_EVT_TIMESCALES +{ + /// @brief Time scale refers to local time. + /// + /// If the local time scale is used to configure the daily jam + /// then the jam occurs at exactly the same time, e.g. always + /// at 2 o'clock according to the configured time zone, regardless + /// whether DST is in effect, or not, and it is not affected by + /// another leap second that might be inserted at some point + /// during operation. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_LOCAL_TIME, + + /// @brief Time scale refers to %UTC. + /// + /// If %UTC is used for the configuration then the jam always occurs + /// at exactly the same %UTC time, which is not affected by another + /// leap second that might be inserted at some point during operation. + /// + /// However, the local time when the jam occurs depends on the + /// local time zone offset, and on the DST status of the + /// configured time zone. + /// + /// For example, if 3 o'clock %UTC has been configured and the + /// local time zone is CET/CEST (i.e. %UTC+1h/%UTC+2h), + /// the jam occurs at 4 o'clock while DST is not in effect, + /// and at 5 o'clock if DST is in effect. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_UTC, + + /// @brief Time scale refers to TAI. + /// + /// If the jam times are configured using the TAI time scale, + /// the effective local time sent in the SMPTE TLV depends on + /// the local time zone offset and DST status just as for + /// ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_UTC, but in addition + /// changes whenefer the TAI/%UTC offset changes due to + /// a leap second. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_TAI, + + /// @brief Time scale refers to GPS system time. + /// + /// Basically the same behavior as with ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_TAI, + /// except that an additional constant offset ::GPS_SEC_BIAS has to be + /// taken into account. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_GPS, + + ///< The number of predefined SMPTE event time scales. + N_MBG_PTP_NG_SMPTE_EVT_TIMESCALES +}; + + + +/** + * @brief Bit masks of predefined time scales for PTP SMPTE jam event times. + * + * Used with ::MBG_PTP_NG_GLB_INFO::supp_smpte_tscales. + * + * @see ::MBG_PTP_NG_SMPTE_EVT_TIMESCALES + */ +enum MBG_PTP_NG_SMPTE_EVT_TIMESCALE_MASKS +{ + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_LOCAL_TIME_MSK = ( 1UL << MBG_PTP_NG_SMPTE_EVT_TIMESCALE_LOCAL_TIME ), ///< See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_LOCAL_TIME. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_UTC_MSK = ( 1UL << MBG_PTP_NG_SMPTE_EVT_TIMESCALE_UTC ), ///< See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_UTC. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_TAI_MSK = ( 1UL << MBG_PTP_NG_SMPTE_EVT_TIMESCALE_TAI ), ///< See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_TAI. + MBG_PTP_NG_SMPTE_EVT_TIMESCALE_GPS_MSK = ( 1UL << MBG_PTP_NG_SMPTE_EVT_TIMESCALE_GPS ) ///< See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_GPS. +}; + + +#define MBG_PTP_NG_SMPTE_EVT_TIMESCALE_STRS \ +{ \ + "PTP (TAI)", \ + "UTC", \ + "Local Time", \ + "GPS" \ +} + + +typedef struct +{ + uint16_t num_instances; ///< Number of currently configured PTP instances. + uint16_t num_uc_masters; ///< Total number of currently configured unicast masters. + uint32_t flags; ///< Current flags, see ::MBG_PTP_NG_FLAG_MASKS. + + uint32_t reserved_2[6]; ///< Reserved, currently always 0. + +} MBG_PTP_NG_GLB_SETTINGS; + + +#define _mbg_swab_ptp_ng_glb_settings( _p ) \ +{ \ + _mbg_swab16( &(_p)->num_instances ); \ + _mbg_swab16( &(_p)->num_uc_masters ); \ + _mbg_swab32( &(_p)->flags ); \ +} + + + +typedef struct mbg_ptp_ng_glb_info_s +{ + MBG_PTP_NG_GLB_SETTINGS settings; ///< The current global configuration for this firmware. + + PTP_CLOCK_ID system_clock_id; ///< System-wide global clock ID, which can be used by all instances. + ///< Only supp., if ::MBG_PTP_NG_FLAG_GLB_CLOCK_ID_MSK is set in ::MBG_PTP_NG_GLB_INFO::supp_flags. + ///< Only used, if ::MBG_PTP_NG_FLAG_GLB_CLOCK_ID_MSK is set in ::MBG_PTP_NG_GLB_SETTINGS::flags. + + uint16_t num_timestampers; ///< Total number of hardware timestampers for this firmware. + uint16_t max_instances; ///< Maximum number of PTP instances (software) for this firmware. + + uint16_t max_uc_masters; ///< Maximum number of uncast masters that can be configured in total for this firmware. + uint16_t max_instc_uc_masters; ///< Maximum number of unicast masters per instance. + + uint32_t supp_protocols; ///< Bitmask of supported network protocols, see ::PTP_NW_PROT_MASKS. + uint32_t supp_delay_mechs; ///< Bit mask of supported delay mechanisms, see ::PTP_DELAY_MECH_MASKS. + uint32_t supp_profiles; ///< Bit mask of supported PTP profiles, see ::PTP_PRESETS: + uint32_t supp_versions; ///< Bit mask of supported PTP protocol versions, see ::PTP_NG_VERSION_MASKS. + uint32_t supp_roles; ///< Bit mask of supported PTP roles, see ::PTP_ROLE_MASKS. + uint32_t supp_flags; ///< Bit mask of supported flags, see ::MBG_PTP_NG_FLAG_MASKS. + uint32_t supp_v1_flags; ///< Bit mask of supported PTPv1 flags, see ::MBG_PTP_NG_V1_FLAG_MASKS. + uint32_t supp_atois; ///< Bit mask of supported Alternate Time Offset Indicators (ATOIs), see ::MBG_PTP_NG_ATOI_MASKS. + + MBG_PTP_NG_INTV_CFG intvs_min; ///< log2 of minimum intervals [s] + MBG_PTP_NG_INTV_CFG intvs_max; ///< log2 of maximum intervals [s] + + uint16_t max_atois; ///< Maximum number of ATOIs that may be used in parallel, see ::MBG_PTP_NG_ATOI_MASKS. + uint16_t supp_smpte_tscales; ///< Bit mask of supported SMPTE event timescales, see ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_MASKS. + uint32_t reserved_2[7]; ///< Reserved, currently always 0. + +} MBG_PTP_NG_GLB_INFO; + + +#define _mbg_swab_ptp_ng_glb_info( _p ) \ +{ \ + _mbg_swab_ptp_ng_glb_settings( &(_p)->settings ); \ + _mbg_swab16( &(_p)->num_timestampers ); \ + _mbg_swab16( &(_p)->max_instances ); \ + _mbg_swab16( &(_p)->max_uc_masters ); \ + _mbg_swab16( &(_p)->max_instc_uc_masters ); \ + _mbg_swab32( &(_p)->supp_protocols ); \ + _mbg_swab32( &(_p)->supp_delay_mechs ); \ + _mbg_swab32( &(_p)->supp_profiles ); \ + _mbg_swab32( &(_p)->supp_versions ); \ + _mbg_swab32( &(_p)->supp_roles ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->supp_v1_flags ); \ + _mbg_swab32( &(_p)->supp_atois ); \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs_min ); \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs_max ); \ + _mbg_swab16( &(_p)->max_atois ); \ +} + + +typedef struct +{ + uint16_t sec_h; ///< Seconds (47:32) + uint16_t reserved_1; + uint32_t reserved_2; + uint32_t sec_l; ///< Seconds (31:0) + uint32_t nsec; ///< Nanoseconds + +} MBG_PTP_NG_TIMESTAMP; + + +#define _mbg_swab_ptp_ng_timestamp( _p ) \ +{ \ + _mbg_swab16( &(_p)->sec_h ); \ + _mbg_swab32( &(_p)->sec_l ); \ + _mbg_swab32( &(_p)->nsec ); \ +} + + +/** + * @brief PTP timestamper modes + * + * @see ::PTP_NG_TSTAMPER_MODE_MASKS + */ +enum PTP_NG_TSTAMPER_MODES +{ + PTP_NG_TSTAMPER_MODE_ALL, ///< Timestamp all incoming packets. + PTP_NG_TSTAMPER_MODE_NTP, ///< Timestamp only NTP packets. + PTP_NG_TSTAMPER_MODE_PTP_V1, ///< Timestamp only PTPv1 packets. + PTP_NG_TSTAMPER_MODE_PTP_V2, ///< Timestamp only PTPv2 (+2.1) packets. + N_PTP_NG_TSTAMPER_MODES +}; + + +/** + * @brief PTP timestamper mode masks used with ::MBG_PTP_NG_TSTAMPER_INFO::supp_modes + * + * @see ::PTP_NG_TSTAMPER_MODES + */ +enum PTP_NG_TSTAMPER_MODE_MASKS +{ + PTP_NG_TSTAMPER_MODE_ALL_MSK = ( 1UL << PTP_NG_TSTAMPER_MODE_ALL ), ///< See ::PTP_NG_TSTAMPER_MODE_ALL + PTP_NG_TSTAMPER_MODE_NTP_MSK = ( 1UL << PTP_NG_TSTAMPER_MODE_NTP ), ///< See ::PTP_NG_TSTAMPER_MODE_NTP + PTP_NG_TSTAMPER_MODE_PTP_V1_MSK = ( 1UL << PTP_NG_TSTAMPER_MODE_PTP_V1 ), ///< See ::PTP_NG_TSTAMPER_MODE_PTP_V1 + PTP_NG_TSTAMPER_MODE_PTP_V2_MSK = ( 1UL << PTP_NG_TSTAMPER_MODE_PTP_V2 ) ///< See ::PTP_NG_TSTAMPER_MODE_PTP_V2 +}; + + +#define PTP_NG_TSTAMPER_MODE_STRS \ +{ \ + "All", \ + "NTP", \ + "PTPv1", \ + "PTPv2" \ +} + + +/** + * @brief PTP timestamper flags + * + * @see ::PTP_NG_TSTAMPER_FLAG_MASKS + */ +enum PTP_NG_TSTAMPER_FLAGS +{ + PTP_NG_TSTAMPER_FLAG_ONE_STEP, ///< timestamp in one-step mode + PTP_NG_TSTAMPER_FLAG_PACKET_GENERATOR, ///< use packet generator to timestamp packets in hardware + PTP_NG_TSTAMPER_FLAG_HYBRID_MODE, ///< use hybrid mode (DelReq. in unicast), only when packet generator is enabled; + ///< otherwise hybrid mode can be enabled/disabled per software instance + PTP_NG_TSTAMPER_FLAG_ALL_DOMAINS, ///< timestamp PTP packets in all domains + PTP_NG_TSTAMPER_FLAG_ALL_PROTOCOLS, ///< timestamp PTP packets of all protocols + PTP_NG_TSTAMPER_FLAG_ALL_IPV6_SCOPES, ///< timestamp PTP packets in all IPv6 multicast scopes + PTP_NG_TSTAMPER_FLAG_SUPP_MULTIPLE_INSTCS, ///< timestamper supports multiple instances (VLANs), not configurable + PTP_NG_TSTAMPER_FLAG_SUPP_P2P_ONE_STEP, ///< timestamper supports P2P one-step mode, not configurable + N_PTP_NG_TSTAMPER_FLAGS +}; + + +/** + * @brief PTP timestamper flag masks used with ::MBG_PTP_NG_TSTAMPER_SETTINGS::flags and ::MBG_PTP_NG_TSTAMPER_INFO::supp_flags + * + * @see ::PTP_NG_TSTAMPER_FLAGS + */ +enum PTP_NG_TSTAMPER_FLAG_MASKS +{ + PTP_NG_TSTAMPER_FLAG_ONE_STEP_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_ONE_STEP ), ///< See ::PTP_NG_TSTAMPER_FLAG_ONE_STEP + PTP_NG_TSTAMPER_FLAG_PACKET_GENERATOR_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_PACKET_GENERATOR ), ///< See ::PTP_NG_TSTAMPER_FLAG_PACKET_GENERATOR + PTP_NG_TSTAMPER_FLAG_HYBRID_MODE_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_HYBRID_MODE ), ///< See ::PTP_NG_TSTAMPER_FLAG_HYBRID_MODE + PTP_NG_TSTAMPER_FLAG_ALL_DOMAINS_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_ALL_DOMAINS ), ///< See ::PTP_NG_TSTAMPER_FLAG_ALL_DOMAINS + PTP_NG_TSTAMPER_FLAG_ALL_PROTOCOLS_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_ALL_PROTOCOLS ), ///< See ::PTP_NG_TSTAMPER_FLAG_ALL_PROTOCOLS + PTP_NG_TSTAMPER_FLAG_ALL_IPV6_SCOPES_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_ALL_IPV6_SCOPES ), ///< See ::PTP_NG_TSTAMPER_FLAG_ALL_IPV6_SCOPES + PTP_NG_TSTAMPER_FLAG_SUPP_MULTIPLE_INSTCS_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_SUPP_MULTIPLE_INSTCS ), ///< See ::PTP_NG_TSTAMPER_FLAG_SUPP_MULTIPLE_INSTCS + PTP_NG_TSTAMPER_FLAG_SUPP_P2P_ONE_STEP_MSK = ( 1UL << PTP_NG_TSTAMPER_FLAG_SUPP_P2P_ONE_STEP ) ///< See ::PTP_NG_TSTAMPER_FLAG_SUPP_P2P_ONE_STEP +}; + + +typedef struct mbg_ptp_ng_tstamper_settings_s +{ + uint8_t mode; ///< timestamper mode, see ::PTP_NG_TSTAMPER_MODES + uint8_t protocol; ///< current protocol, see ::PTP_NW_PROTS + uint8_t domain; ///< current PTPv2 domain number (0..255) + uint8_t ipv6_multicast_scope; ///< One of the ::IPV6_MULTICAST_SCOPES used for PTP IPv6 multicast. + + uint32_t flags; ///< See ::PTP_NG_TSTAMPER_FLAG_MASKS + + uint32_t reserved_2[6]; ///< reserved, currently always 0 + +} MBG_PTP_NG_TSTAMPER_SETTINGS; + + +#define _mbg_swab_ptp_ng_tstamper_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->flags ); \ +} + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + MBG_PTP_NG_TSTAMPER_SETTINGS settings; + +} MBG_PTP_NG_TSTAMPER_SETTINGS_IDX; + + +#define _mbg_swab_ptp_ng_tstamper_settings_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_tstamper_settings( &(_p)->settings ); \ +} + + +typedef struct mbg_ptp_ng_tstamper_info_s +{ + MBG_PTP_NG_TSTAMPER_SETTINGS settings; + + PTP_INTF phys_intf; ///< the physical interface name this timestamper belongs to + uint32_t supp_modes; ///< bitmask of supported timestamper modes, see ::PTP_NG_TSTAMPER_MODE_MASKS + uint32_t supp_protocols; ///< bitmask of supported network protocols, see ::PTP_NW_PROT_MASKS + uint32_t supp_roles; ///< bitmask of supported PTP roles on this timestamper, see ::PTP_ROLE_MASKS + uint32_t supp_flags; ///< bitmask of supported features, see ::PTP_NG_TSTAMPER_FLAG_MASKS + uint32_t max_ptp_packets; ///< Maximum number of PTP generated packets per second + uint32_t max_ntp_packets; ///< Maximum number of NTP generated packets per second + uint16_t max_ptp_uc_slaves; ///< Maximum number of PTP Unicast slaves + uint16_t reserved_1; ///< reserved, currently always 0 + + uint32_t reserved_2[5]; ///< reserved, currently always 0 + +} MBG_PTP_NG_TSTAMPER_INFO; + + +#define _mbg_swab_ptp_ng_tstamper_info( _p ) \ +{ \ + _mbg_swab_ptp_ng_tstamper_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab32( &(_p)->supp_protocols ); \ + _mbg_swab32( &(_p)->supp_roles ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + MBG_PTP_NG_TSTAMPER_INFO info; + +} MBG_PTP_NG_TSTAMPER_INFO_IDX; + + +#define _mbg_swab_ptp_ng_tstamper_info_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_tstamper_info( &(_p)->info ); \ +} + + +typedef struct mbg_ptp_ng_tstamper_status_s +{ + MBG_PTP_NG_TIMESTAMP current_time; ///< current tstamper time + PTP_TIME_INTERVAL offset_from_int_ref; ///< current offset between tstamper time and internal reference + uint8_t utilization; ///< current resource utilization (msg/sec) in % + uint8_t reserved_1[7]; ///< reserved, currently always 0 + + uint32_t reserved_2[12]; ///< reserved, currently always 0 + +} MBG_PTP_NG_TSTAMPER_STATUS; + + +#define _mbg_swab_ptp_ng_tstamper_status( _p ) \ +{ \ + _mbg_swab_ptp_ng_timestamp( &(_p)->current_time ); \ + _mbg_swab_ptp_time_interval( &(_p)->offset_from_int_ref ); \ +} + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + MBG_PTP_NG_TSTAMPER_STATUS status; + +} MBG_PTP_NG_TSTAMPER_STATUS_IDX; + + +#define _mbg_swab_ptp_ng_tstamper_status_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_tstamper_status( &(_p)->status ); \ +} + + +enum MBG_PTP_NG_SERVO_FLAGS +{ + MBG_PTP_NG_SERVO_FLAG_USE_IIR_FILTER, ///< TODO: Please add describing comment + MBG_PTP_NG_SERVO_FLAG_USE_SPIKE_FILTER, ///< TODO: Please add describing comment + MBG_PTP_NG_SERVO_FLAG_USE_SAMPLE_RATE_CONVERTER, ///< TODO: Please add describing comment + MBG_PTP_NG_SERVO_FLAG_COLD_START, ///< PTP stack starts with a default drift value + N_MBG_PTP_NG_SERVO_FLAGS +}; + + +enum MBG_PTP_NG_SERVO_FLAG_MASKS +{ + MBG_PTP_NG_SERVO_FLAG_USE_IIR_FILTER_MSK = (1UL << MBG_PTP_NG_SERVO_FLAG_USE_IIR_FILTER), ///< See ::MBG_PTP_NG_SERVO_FLAG_USE_IIR_FILTER + MBG_PTP_NG_SERVO_FLAG_USE_SPIKE_FILTER_MSK = (1UL << MBG_PTP_NG_SERVO_FLAG_USE_SPIKE_FILTER), ///< See ::MBG_PTP_NG_SERVO_FLAG_USE_SPIKE_FILTER + MBG_PTP_NG_SERVO_FLAG_USE_SAMPLE_RATE_CONVERTER_MSK = (1UL << MBG_PTP_NG_SERVO_FLAG_USE_SAMPLE_RATE_CONVERTER), ///< See ::MBG_PTP_NG_SERVO_FLAG_USE_SAMPLE_RATE_CONVERTER + MBG_PTP_NG_SERVO_FLAG_COLD_START_MSK = (1UL << MBG_PTP_NG_SERVO_FLAG_COLD_START), ///< See ::MBG_PTP_NG_SERVO_FLAG_COLD_START +}; + + +typedef struct +{ + int64_t inbound_delta_rate_max; ///< TODO: Please add describing comment + int64_t inbound_anti_windup_max; ///< TODO: Please add describing comment + int64_t outbound_delta_rate_max; ///< TODO: Please add describing comment + int64_t outbound_anti_windup_max; ///< TODO: Please add describing comment + + uint8_t reserved_1; ///< reserved, currently always 0 + int8_t lucky_packet_flt_depth; ///< TODO: Please add describing comment + uint16_t lucky_packet_median; ///< TODO: Please add describing comment + uint32_t flags; ///< See ::MBG_PTP_NG_SERVO_FLAG_MASKS + + uint32_t outbound_pi_k; ///< TODO: Please add describing comment + uint32_t outbound_pi_t; ///< TODO: Please add describing comment + + uint16_t iir_m2s_smin; ///< TODO: Please add describing comment + uint16_t iir_path_smin; ///< TODO: Please add describing comment + int8_t iir_log_adj_prd; ///< TODO: Please add describing comment + int8_t iir_log_adj_gain; ///< TODO: Please add describing comment + uint16_t reserved_2; ///< reserved, currently always 0 + + uint32_t inbound_pi_k; ///< TODO: Please add describing comment + uint32_t inbound_pi_t; ///< TODO: Please add describing comment + + int32_t boundary; ///< Sync Boundary in scaledNs [65536000] -> 1 microsecond + int32_t change_epoch_boundary; ///< Max epoch jump in scaledNs before hard time step is done [32768000000000] -> 0.5 sec + + uint8_t adjust_interval; ///< -8..+8 + uint8_t reserved_3; ///< reserved, currently always 0 + uint16_t reserved_4; ///< reserved, currently always 0 + uint32_t reserved_5; ///< reserved, currently always 0 + + uint32_t reserved_6[4]; ///< reserved, currently always 0 + +} MBG_PTP_NG_SERVO_SETTINGS; + + +#define _mbg_swab_ptp_ng_servo_settings( _p ) \ +{ \ + _mbg_swab64( &(_p)->inbound_delta_rate_max ); \ + _mbg_swab64( &(_p)->inbound_anti_windup_max ); \ + _mbg_swab64( &(_p)->outbound_delta_rate_max ); \ + _mbg_swab64( &(_p)->outbound_anti_windup_max ); \ + _mbg_swab16( &(_p)->lucky_packet_median ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->outbound_pi_k ); \ + _mbg_swab32( &(_p)->outbound_pi_t ); \ + _mbg_swab16( &(_p)->iir_m2s_smin ); \ + _mbg_swab16( &(_p)->iir_path_smin ); \ + _mbg_swab32( &(_p)->inbound_pi_k ); \ + _mbg_swab32( &(_p)->inbound_pi_t ); \ + _mbg_swab32( &(_p)->boundary ); \ + _mbg_swab32( &(_p)->change_epoch_boundary ); \ +} + + +typedef struct +{ + uint8_t clk_class_never_sync; ///< Fixed clock class if clock is free running, 0 means automatic + uint8_t clk_class_sync; ///< Fixed clock class if clock is synced, 0 means automatic + uint8_t clk_class_holdover; ///< Fixed clock class if clock is in holdover, 0 means automatic + uint8_t time_source; ///< Fixed PTP Time Source, 0 means automatic + uint8_t clk_accuracy; ///< Fixed clock accuracy, 0 means automatic + + uint8_t reserved_1; ///< Fixed clock accuracy, 0 means automatic + uint16_t fixed_clk_variance; ///< Fixed clock variance, 0 means automatic + + uint32_t reserved_2[4]; ///< reserved, currently always 0 + +} MBG_PTP_NG_FIXED_CLK_QLTY; + + +#define _mbg_swab_ptp_ng_fixed_clk_qlty( _p ) \ +{ \ + _mbg_swab16( &(_p)->fixed_clk_variance ); \ +} + + + +/** + * @brief Additional parameters for PTP Power Profile + */ +typedef struct +{ + uint32_t gm_time_incaccuracy; ///< Pre-defined GM time inaccuracy from master [ns] + uint32_t network_time_incaccuracy; ///< Configurable network inaccuracy from master [ns] + + uint8_t grandmaster_id; ///< [::PTP_POWER_PROFILE_GM_ID_MIN..::PTP_POWER_PROFILE_GM_ID_MAX] + uint8_t reserved[7]; ///< reserved, currently always 0 + +} MBG_PTP_NG_C37238_2011_SETTINGS; + + +#define _mbg_swab_ptp_ng_c37238_2011_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->gm_time_incaccuracy ); \ + _mbg_swab32( &(_p)->network_time_incaccuracy ); \ +} + + +typedef struct +{ + uint32_t total_inaccuracy; ///< Total inaccuracy in [ns] + uint16_t grandmaster_id; ///< Full 16 Bit Grandmaster ID + uint16_t reserved_1; ///< reserved, currently always 0 + +} MBG_PTP_NG_C37238_2017_SETTINGS; + + +#define _mbg_swab_ptp_ng_c37238_2017_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->total_inaccuracy ); \ + _mbg_swab16( &(_p)->grandmaster_id ); \ +} + + +/** + * @brief SMPTE System Frame Rates according to SMPTE ST 2059-2 + * + */ +enum MBG_PTP_NG_SMPTE_FRAME_RATES +{ + MBG_PTP_NG_SMPTE_FRAME_RATE_23_98HZ, + MBG_PTP_NG_SMPTE_FRAME_RATE_24HZ, + MBG_PTP_NG_SMPTE_FRAME_RATE_25HZ, + MBG_PTP_NG_SMPTE_FRAME_RATE_29_97HZ, + MBG_PTP_NG_SMPTE_FRAME_RATE_50HZ, + MBG_PTP_NG_SMPTE_FRAME_RATE_59_94HZ, + N_MBG_PTP_NG_SMPTE_FRAME_RATES +}; + + +#define MBG_PTP_NG_SMPTE_FRAME_RATE_STR \ +{ \ + "23.98 Hz", \ + "24 Hz", \ + "25 Hz", \ + "29.97 Hz", \ + "50 Hz", \ + "59.94 Hz" \ +} + + +#define MBG_PTP_NG_SMPTE_FRAME_RATE_NUM \ +{ \ + 24000, \ + 24000, \ + 25000, \ + 30000, \ + 50000, \ + 60000 \ +} + + +#define MBG_PTP_NG_SMPTE_FRAME_RATE_DENUM \ +{ \ + 1001, \ + 1000, \ + 1000, \ + 1001, \ + 1000, \ + 1001 \ +} + + +/** + * @brief SMPTE Time Address Flags according to SMPTE ST 2059-2 + * + */ +enum MBG_PTP_NG_SMPTE_TIME_ADDR_FLAGS +{ + MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_DROP_FRAME, + MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_COLOR_FRAME, + N_MBG_PTP_NG_SMPTE_TIME_ADDR_FLAGS +}; + + +enum MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_MASKS +{ + MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_DROP_FRAME_MSK = ( 1UL << MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_DROP_FRAME ), ///< See ::MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_DROP_FRAME + MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_COLOR_FRAME_MSK = ( 1UL << MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_COLOR_FRAME ) ///< See ::MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_COLOR_FRAME +}; + + +/** + * @brief SMPTE jam modes. + * + * Used with ::MBG_PTP_NG_SMPTE_20592_SETTINGS::next_jam_mode, which determines + * how to interpret the value in ::MBG_PTP_NG_SMPTE_20592_SETTINGS::jam_event. + */ +enum MBG_PTP_NG_SMPTE_JAM_MODES +{ + /// @brief Jam mode is disabled. + MBG_PTP_NG_SMPTE_JAM_MODE_DISABLED, + + /// @brief Daily jam at the specified seconds since midnight. + /// + /// The variable ::MBG_PTP_NG_SMPTE_20592_SETTINGS::jam_event + /// contains the number of seconds since midnight when the + /// jam is to occur. + /// The code in ::MBG_PTP_NG_SMPTE_20592_SETTINGS::event_timescale + /// indicates which time scale 'midnight' refers to. The default + /// timescale should be ::MBG_PTP_NG_SMPTE_EVT_TIMESCALE_LOCAL_TIME. + /// See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALES. + MBG_PTP_NG_SMPTE_JAM_MODE_DAILY, + + /// @brief Next jam at the specified next absolute time. + /// + /// The variable ::MBG_PTP_NG_SMPTE_20592_SETTINGS::jam_event + /// contains the absolute time in POSIX time_t-like format when + /// the jam is to occur. + /// The code in ::MBG_PTP_NG_SMPTE_20592_SETTINGS::event_timescale + /// indicates the time scale associated with the time stamp. + /// See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALES. + MBG_PTP_NG_SMPTE_JAM_MODE_SINGLE, + + /// @brief Next jam occurs when the local time is stepped. + /// + /// The variable ::MBG_PTP_NG_SMPTE_20592_SETTINGS::jam_event + /// contains the absolute time in POSIX time_t-like format when + /// the jam is to occur, and this time should match + /// ::MBG_PTP_NG_SMPTE_20592_STATUS::time_of_next_jump. + MBG_PTP_NG_SMPTE_JAM_MODE_NEXT_DISCONT_ON_LOCAL_TIME_CHANGE, + + N_MBG_PTP_NG_SMPTE_JAM_MODES ///< The number of known PTP SMPTE jam modes. +}; + + +#define MBG_PTP_NG_SMPTE_JAM_MODE_STRS \ +{ \ + "Disabled", \ + "Daily Jam Event", \ + "Single Jam Event", \ + "Next discontinuity in Local Time" \ +} + + +/** + * @brief Additional parameters for SMPTE ST 2059-2 profile + * + * This stucture holds the configuration for PTP NG SMPTE profile. + * The status can not be represented by this structure, because it does not contain jam and jump times + */ +typedef struct +{ + uint32_t default_frame_rate_num; ///< See ::MBG_PTP_NG_SMPTE_FRAME_RATES and ::MBG_PTP_NG_SMPTE_FRAME_RATE_NUM. + uint32_t default_frame_rate_denum; ///< See ::MBG_PTP_NG_SMPTE_FRAME_RATES and ::MBG_PTP_NG_SMPTE_FRAME_RATE_DENUM. + + uint32_t time_address_flags; ///< See ::MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_MASKS. + uint16_t reserved; ///< Reserved, currently always 0. + uint8_t next_jam_mode; ///< See ::MBG_PTP_NG_SMPTE_JAM_MODES. + uint8_t event_timescale; ///< See ::MBG_PTP_NG_SMPTE_EVT_TIMESCALES. + + /// @brief Jam event time configuration. + /// + /// Depending on the values of #next_jam_mode (see ::MBG_PTP_NG_SMPTE_JAM_MODES) + /// and #event_timescale (see ::MBG_PTP_NG_SMPTE_EVT_TIMESCALES), + /// this field can contain an absolute time for a single jam event, + /// or a number of seconds since midnight indicating when the + /// daily jam is to occur. + /// + /// The jam time sent in the SMPTE TLVs has to be calculated + /// according to these settings. + int64_t jam_event; + +} MBG_PTP_NG_SMPTE_20592_SETTINGS; + + +#define _mbg_swab_ptp_ng_smpte_20592_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->default_frame_rate_num ); \ + _mbg_swab32( &(_p)->default_frame_rate_denum ); \ + _mbg_swab32( &(_p)->time_address_flags ); \ + _mbg_swab64( &(_p)->jam_event ); \ +} + + + +enum MBG_PTP_NG_82751_FLAGS +{ + MBG_PTP_NG_82751_FLAG_USE_ALT_MC_ADDRESS, ///< Use Alternative (non-forwardable) multicast address + MBG_PTP_NG_82751_FLAG_PORT_NOT_SLAVE, ///< PTP Instance cannot become a SLAVE + N_MBG_PTP_NG_82751_FLAGS +}; + + +enum MBG_PTP_NG_82751_FLAG_MSKS +{ + MBG_PTP_NG_82751_FLAG_USE_ALT_MC_ADDRESS_MSK = (1UL << MBG_PTP_NG_82751_FLAG_USE_ALT_MC_ADDRESS), ///< See ::MBG_PTP_NG_82751_FLAG_USE_ALT_MC_ADDRESS + MBG_PTP_NG_82751_FLAG_PORT_NOT_SLAVE_MSK = (1UL << MBG_PTP_NG_82751_FLAG_PORT_NOT_SLAVE) ///< See ::MBG_PTP_NG_82751_FLAG_PORT_NOT_SLAVE +}; + + +/** + * @brief Additional parameters for Telecom8275.1 profile + */ +typedef struct +{ + uint8_t port_local_priority; ///< TODO: Please add describing comment + uint8_t default_local_priority; ///< TODO: Please add describing comment + uint16_t reserved; ///< reserved, currently always 0 + + uint32_t flags; ///< Bitmask used with ::MBG_PTP_NG_82751_FLAG_MSKS + +} MBG_PTP_NG_TELECOM_G82751_SETTINGS; + + +#define _mbg_swab_ptp_ng_telecom_g82751_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->flags ); \ +} + + +/** + * @brief Large Scaled nanoseconds structure (96 bit integer). + * This format is only used by 802.1as. + */ +typedef struct +{ + int64_t ns_l; + int32_t ns_h; + int32_t reserved; // used for alignment +} MBG_PTP_NG_LARGE_SCALED_NS; + + +enum MBG_PTP_NG_8021AS_FLAGS +{ + MBG_PTP_NG_8021AS_FLAG_AS_CAPABLE, ///< this time-aware system and the time-aware system at the other end of the link attached to this port can interoperate with each other via IEEE 802.1AS + N_MBG_PTP_NG_8021AS_FLAGS +}; + + +enum MBG_PTP_NG_8021AS_FLAG_MSKS +{ + MBG_PTP_NG_8021AS_FLAG_AS_CAPABLE_MSK = (1UL << MBG_PTP_NG_8021AS_FLAG_AS_CAPABLE), ///< See ::MBG_PTP_NG_8021AS_FLAG_AS_CAPABLE +}; + + +/** + * @brief Additional parameters for IEEE 802.1AS profile + * TODO: Shall this really be settings or rather status? + */ +typedef struct +{ + PTP_TIME_INTERVAL port_neighbor_prop_delay_thresh; ///< Propagation time threshold, above which a port is not considered capable of participating in the IEEE 802.1AS protocol. + int64_t port_last_gm_phase_change; ///< Current phase difference (offset) to the current GM (in slave and passive state) on the current port. + ///< Will be used as @a last_gm_phase_change after this clock becomes GM. + MBG_PTP_NG_LARGE_SCALED_NS last_gm_phase_change; ///< Global last phase change of the clockSource/GM. Is changed whenever the time base changes. + PTP_NG_PORT_IDENTITY port_as_neighbor; ///< PortId of the current @a asCapable neighbor, only if @a asCapable is true. + int32_t port_last_gm_freq_change; ///< Current frequency rate ratio to the current GM (in slave and passive state). + ///< Will be used as lastGmFreqChange after this clock becomes GM. + int32_t cumulative_scaled_rate_offset; ///< Ratio of the frequency of the clockSource/GM to the frequency of the local clock (rateRatio * 1.0) * (2^41). + int32_t last_gm_freq_change; ///< (rateRatio * 2^41) Fractional frequency offset of the current clockSource/GM to the last clockSource/GM. + ///< Changes whenever the time base changes. + int32_t port_neighbor_rate_ratio; ///< Current rate ratio to the port neighbor in scaled ratio (rateRatio * 2^41). + uint16_t gm_time_base_indicator; ///< Used to identify the time base. If this clock acts as GM, it has to be managed + ///< via shared mem., equivalent to clockSourceTimeBaseIndicator. + uint16_t reserved_1; + uint32_t flags; ///< See ::MBG_PTP_NG_8021AS_FLAGS. + uint32_t reserved_2[2]; + +} MBG_PTP_NG_IEEE_8021AS_SETTINGS; + + + +typedef union +{ + char u[128]; + + MBG_PTP_NG_C37238_2011_SETTINGS c37238_2011; ///< Power Profile C37.238-2011 + MBG_PTP_NG_C37238_2017_SETTINGS c37238_2017; ///< Power Profile C37.238-2017 + MBG_PTP_NG_SMPTE_20592_SETTINGS smpte_20592; ///< SMPTE Profile ST 2059-2 + MBG_PTP_NG_TELECOM_G82751_SETTINGS g82751; ///< Telecom Profile ITU-T. G.8275.1 + MBG_PTP_NG_IEEE_8021AS_SETTINGS ieee8021as; ///< IEEE 802.1AS Profile + +} MBG_PTP_NG_PROFILE_SETTINGS_U; + + +#define _mbg_swab_ptp_ng_profile_settings_u( _profile, _p ) \ +do \ +{ \ + switch ( (_profile) ) \ + { \ + case PTP_PRESETS_POWER: \ + _mbg_swab_ptp_ng_c37238_2011_settings( &(_p)->c37238_2011 ); \ + break; \ + \ + case PTP_PRESETS_C37238_2017: \ + _mbg_swab_ptp_ng_c37238_2017_settings( &(_p)->c37238_2017 ); \ + break; \ + \ + case PTP_PRESETS_SMPTE: \ + _mbg_swab_ptp_ng_smpte_20592_settings( &(_p)->smpte_20592 ); \ + break; \ + \ + case PTP_PRESETS_TELECOM_PHASE: \ + _mbg_swab_ptp_ng_telecom_g82751_settings( &(_p)->g82751 ); \ + break; \ + \ + default: break; \ + } \ +} while ( 0 ) + + + +/** + * @brief A name of a local time zone which can be longer than used in::TZDL. + */ +typedef char MBG_PTP_NG_ATOI_TZ_NAME[12]; + + + +/** + * @brief A structure used to configure a PTP instance. + */ +typedef struct mbg_ptp_ng_instc_settings_s +{ + uint32_t tstamper_idx; ///< Index of the timestamper that is active for this config running on interface @a #intf_label. + uint16_t assigned_port_id; ///< Port ID for this instance. Read-only for user interfaces, must be assigned by the managing process. + uint16_t reserved_1; ///< Reserved, currently always 0. + + PTP_INTF intf_label; ///< Interface name (IPv4/L2) or IPv6 address of logical/VLAN interface linked to this config. + + PTP_PORT_IDENTITY custom_port_id; ///< Overwrite port ID of this PTP port with global clock ID and suitable port ID. + ///< Only used if ::MBG_PTP_NG_FLAG_CUSTOM_PORT_ID_MSK is set in @a #flags. + uint16_t reserved_2; ///< Reserved, currently always 0. + uint8_t log_severity; ///< Sets the log level of the PTP Stack. Range from 0 (errors only) to 4. + uint8_t dsf; ///< Differentiated service field (IPv4) for PTP event messages -> 6 bit (MSB) DSCP, 2 bit ECN. + uint8_t ipv6_multicast_scope; ///< One of the ::IPV6_MULTICAST_SCOPES used for PTP IPv6 multicast. + uint8_t role; ///< One of the supported PTP roles, see ::PTP_ROLES. + + uint8_t profile; ///< Selected PTP preset or profile, see ::PTP_PRESETS. + uint8_t domain_number; ///< The PTP clock domain number, 0..255. + uint8_t reserved_4[6]; ///< Reserved, currently always 0. + + uint8_t delay_mech; ///< See ::PTP_DELAY_MECHS. + uint8_t protocol; ///< See ::PTP_NW_PROTS. + uint8_t priority_1; ///< Default DS priority 1. + uint8_t priority_2; ///< Default DS priority 2. + MBG_PTP_NG_INTV_CFG intvs; ///< Interval settings for this PTP instance. + + uint8_t min_gm_clk_class; ///< Minimum acceptable GM clock class for clock adjustment in slave mode, 0 means accept all. + uint8_t min_gm_clk_accuracy; ///< Minimum acceptable GM clock accuracy for clock adjustment in slave mode, 0 means accept all. + uint16_t min_gm_clk_variance; ///< Minimum acceptable GM clock variance for clock adjustment in slave mode, 0 means accept all. + uint8_t multicast_ttl; ///< Sets the multicast TTL value in IPv4 or multicast hop count in IPv6. 1..255, default 5. + uint8_t unicast_ttl; ///< Sets the unicast TTL value in IPv4 or unicast hop count in IPv6. 1..255, default 128. + uint8_t ann_rcpt_timeout; ///< Announce msg. receipt timeout, see ::PTP_ANN_RCPT_TIMEOUT_LIMITS. + uint8_t v1_clock_stratum; ///< Clock stratum parameter for PTPv1 stack + + char v1_subdomain_name[PTP_SUBDOMAIN_NAME_LENGTH]; ///< Subdomain string for PTPv1 stack. + + uint32_t upper_bound; ///< Sync. state set to uncalibrated if above this limit [ns], default 0 (ignored). + uint32_t lower_bound; ///< Sync. state set to slave if below this limit [ns], default 0 (ignored). + + int32_t fast_locking_boundary; ///< Determines if fast locking is used after a master was selected or changed [ns], in slave mode only. + int32_t delay_asymmetry; ///< Used to compensate asymmetries [ns], default 0. + + MBG_PTP_NG_FIXED_CLK_QLTY fixed_quality; ///< Fixed Clock Quality as manual override used in BMCA. + ///< Only used if ::MBG_PTP_NG_FLAG_FIXED_QUALITY_MSK is set in @a #flags. + MBG_PTP_NG_SERVO_SETTINGS servo_settings; ///< PTP Clock Servo Settings used in slave mode to adjust TSU time. + MBG_PTP_NG_PROFILE_SETTINGS_U profile_settings; ///< Union that includes all profile specific parameters. + ///< The profile type to be used is determined by the @a #profile parameter. + + uint32_t atois; ///< Activated ATOI TLVs, see ::MBG_PTP_NG_GLB_INFO::max_atois and ::MBG_PTP_NG_ATOI_MASKS + uint32_t flags; ///< See ::MBG_PTP_NG_FLAG_MASKS. + + TZDL custom_atoi; ///< Alternate Time Offset Indicator, used to derive local time + ///< from the TAI time of the grandmaster. + MBG_PTP_NG_ATOI_TZ_NAME names[2]; ///< Local time zone names for DST off and DST on. + ///< Can be longer than the names in ::TZDL @a #custom_atoi. + + uint32_t v1_flags; ///< See ::MBG_PTP_NG_V1_FLAG_MASKS. + uint32_t reserved_5[3]; ///< Reserved, currently always 0. + + char alias[32]; ///< A configurable, descriptive name for the PTP instance, just informational. + +} MBG_PTP_NG_INSTC_SETTINGS; + + +#define _mbg_swab_ptp_ng_instc_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->tstamper_idx ); \ + _mbg_swab16( &(_p)->assigned_port_id ); \ + _mbg_swab_ptp_port_identity( &(_p)->custom_port_id ); \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs ); \ + _mbg_swab16( &(_p)->min_gm_clk_variance ); \ + _mbg_swab32( &(_p)->upper_bound ); \ + _mbg_swab32( &(_p)->lower_bound ); \ + _mbg_swab32( &(_p)->fast_locking_boundary ); \ + _mbg_swab32( &(_p)->delay_asymmetry ); \ + _mbg_swab_ptp_ng_fixed_clk_qlty( &(_p)->fixed_quality ); \ + _mbg_swab_ptp_ng_servo_settings( &(_p)->servo_settings ); \ + _mbg_swab_ptp_ng_profile_settings_u( (_p)->profile, &(_p)->profile_settings ); \ + _mbg_swab32( &(_p)->atois ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab_tzdl( &(_p)->custom_atoi ); \ + _mbg_swab32( &(_p)->v1_flags ); \ +} \ +while(0) + + + +/** + * @brief ::TODO + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< Padding for 8-byte alignment, some settings contain int64_t. + + MBG_PTP_NG_INSTC_SETTINGS settings; + +} MBG_PTP_NG_INSTC_SETTINGS_IDX; + + +#define _mbg_swab_ptp_ng_instc_settings_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_instc_settings( &(_p)->settings ); \ +} + + +/** + * @brief A structure to used to query the current configuration of a PTP Instance + */ +typedef struct mbg_ptp_ng_instc_info_s +{ + MBG_PTP_NG_INSTC_SETTINGS settings; ///< The current configuration. + + uint32_t reserved[4]; ///< Reserved, currently always 0 + +} MBG_PTP_NG_INSTC_INFO; + + +#define _mbg_swab_ptp_ng_instc_info( _p ) \ +{ \ + _mbg_swab_ptp_ng_instc_settings( &(_p)->settings ); \ +} + + +/** + * @brief + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< Padding for 8-byte alignment, some settings contain int64_t. + + MBG_PTP_NG_INSTC_INFO info; + +} MBG_PTP_NG_INSTC_INFO_IDX; + + +#define _mbg_swab_ptp_ng_instc_info_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_instc_info( &(_p)->info ); \ +} + +typedef struct +{ + int64_t min; + int64_t mean; + int64_t median; + int64_t stdDev; +} MBG_PTP_NG_PKT_STATS; + + +#define _mbg_swab_ptp_ng_pkt_stats( _p ) \ +{ \ + _mbg_swab64( &(_p)->min ); \ + _mbg_swab64( &(_p)->mean ); \ + _mbg_swab64( &(_p)->median ); \ + _mbg_swab64( &(_p)->stdDev ); \ +} + + +#define MAX_MBG_PTP_NG_ATOI_STATUS 3 + + +typedef struct +{ + uint8_t key; ///< An index number, see ::MBG_PTP_NG_ATOIS. + uint8_t reserved_1; ///< Reserved, currently always 0. + PTP_PKT_TSTAMP_SECS time_of_next_jump; ///< Time when the next discontinuity will occur, in seconds. + + PTP_TLV_TIME_OFFS current_offset; ///< Offset of the current time scale, in seconds. + PTP_TLV_TIME_OFFS jump_seconds; ///< Size of next discontinuity, in seconds. + + MBG_PTP_NG_ATOI_TZ_NAME display_name; ///< Name of the ATOI timezone. + uint8_t flags; ///< Reserved, currently always 0. + uint8_t reserved_2[3]; ///< Reserved, currently always 0. + +} MBG_PTP_NG_ATOI_STATUS; + + +#define _mbg_swab_ptp_ng_atoi_status( _p ) \ +{ \ + _mbg_swab32( &(_p)->current_offset ); \ + _mbg_swab32( &(_p)->jump_seconds ); \ +} + + +enum MBG_PTP_NG_SMPTE_MASTER_LOCKING_STATUS +{ + MBG_PTP_NG_SMPTE_MASTER_NOT_IN_USE, + MBG_PTP_NG_SMPTE_MASTER_FREE_RUN, + MBG_PTP_NG_SMPTE_MASTER_COLD_LOCKING, + MBG_PTP_NG_SMPTE_MASTER_WARM_LOCKING, + MBG_PTP_NG_SMPTE_MASTER_LOCKED, + N_MBG_PTP_NG_SMPTE_MASTER_LOCKING_STATUS +}; + + +#define MBG_PTP_NG_SMPTE_MASTER_LOCKING_STATUS_STRS \ +{ \ + "Not in use", \ + "Free Run", \ + "Cold Locking", \ + "Warm Locking", \ + "Locked" \ +} + + +typedef struct +{ + uint32_t system_frame_rate_num; ///< See ::MBG_PTP_NG_SMPTE_FRAME_RATES and ::MBG_PTP_NG_SMPTE_FRAME_RATE_NUM. + uint32_t system_frame_rate_denum; ///< See ::MBG_PTP_NG_SMPTE_FRAME_RATES and ::MBG_PTP_NG_SMPTE_FRAME_RATE_DENUM. + + uint32_t time_address_flags; ///< See ::MBG_PTP_NG_SMPTE_TIME_ADDR_FLAG_MASKS. + uint8_t master_locking_status; ///< See ::MBG_PTP_NG_SMPTE_MASTER_LOCKING_STATUS. + PTP_TLV_DST_FLAGS daylight_saving; ///< Daylight saving flags, see ::PTP_TLV_DST_FLAG_MSKS. + PTP_TLV_LS_FLAGS leap_second_jump; ///< Leap second Flags, see ::PTP_TLV_LS_FLAG_MSKS. + uint8_t reserved_1; ///< Reserved, currently always 0 + + /// @brief Offset in seconds of Local Time from grandmaster PTP time. + /// + /// For example, if Local Time is Eastern Standard Time (North America) %UTC-5 and the + /// number of leap seconds is 37, the value will be -18037 s. + PTP_TLV_TIME_OFFS current_local_offset; + + /// @brief The size of the next discontinuity in local time, in seconds. + /// + /// A value of 0 indicates that no discontinuity is expected. A positive value + /// indicates that the discontinuity will increase the @a #current_local_offset. + PTP_TLV_TIME_OFFS jump_seconds; + + /// @brief Time at which the next discontinuity of the @a #current_local_offset will occur. + /// + /// Refers to the second portion of the grandmaster PTP time. + /// The discontinuity occurs at the start of the second indicated. + /// If no discontinuity has been scheduled, the value is 0. + PTP_PKT_TSTAMP_SECS time_of_next_jump; + + /// @brief Time at which the next daily jam is to occur. + /// + /// Refers to the second portion of the grandmaster PTP time. + /// If no daily jam has been scheduled, the value is 0. + PTP_PKT_TSTAMP_SECS time_of_next_jam; + + /// @brief Time at which the previous daily jam occurred. + /// + /// Refers to the second portion of the grandmaster PTP time. + /// If the time of the previous jam is unknown, the value is 0. + PTP_PKT_TSTAMP_SECS time_of_previous_jam; + + /// @brief Reserved, currently always 0. + uint16_t reserved_2; + + /// @brief Local time offset at the previous daily jam. + /// + /// The value of @a #current_local_offset at the previous daily jam time. + /// If a discontinuity of local time occurs at the jam time, this parameter + /// reflects the offset after the discontinuity. + PTP_TLV_TIME_OFFS previous_jam_local_offset; + +} MBG_PTP_NG_SMPTE_20592_STATUS; + + +#define _mbg_swab_ptp_ng_smpte_20592_status( _p ) \ +{ \ + _mbg_swab32( &(_p)->system_frame_rate_num ); \ + _mbg_swab32( &(_p)->system_frame_rate_denum ); \ + _mbg_swab32( &(_p)->time_address_flags ); \ + _mbg_swab32( &(_p)->current_local_offset ); \ + _mbg_swab32( &(_p)->jump_seconds ); \ + _mbg_swab32( &(_p)->previous_jam_local_offset ); \ +} + + + +/** + * @brief Daylight saving flags used in PTP TLVs. + * + * Used with ::PTP_TLV_DST_FLAGS. + */ +enum PTP_TLV_DST_FLAG_MSKS +{ + PTP_TLV_DST_FLAG_DST = 0x01, ///< Bit 0: DST currently in effect. + PTP_TLV_DST_FLAG_DST_AT_NEXT_JMP = 0x02, ///< Bit 1: DST in effect at next discontinuity. + PTP_TLV_DST_FLAG_DST_AT_PRV_JAM = 0x04 ///< Bit 2: DST in effect at previous jam time. + // Other bits are reserved. +}; + + + +/** + * @brief Leap second flags used in PTP TLVs. + * + * Used with ::PTP_TLV_LS_FLAGS. + */ +enum PTP_TLV_LS_FLAG_MSKS +{ + PTP_TLV_LS_FLAG_LEAP_SEC = 0x01 ///< Bit 0: Next discontinuity due to leap second. + // Other bits are reserved. +}; + + + +typedef union +{ + char u[128]; + + MBG_PTP_NG_C37238_2011_SETTINGS c37238_2011; ///< Power Profile C37.238-2011 + MBG_PTP_NG_C37238_2017_SETTINGS c37238_2017; ///< Power Profile C37.238-2017 + MBG_PTP_NG_SMPTE_20592_STATUS smpte_20592; ///< SMPTE Profile ST 2059-2 + MBG_PTP_NG_TELECOM_G82751_SETTINGS g82751; ///< Telecom Profile ITU-T. G.8275.1 + MBG_PTP_NG_IEEE_8021AS_SETTINGS ieee8021as; ///< IEEE 802.1AS Profile + +} MBG_PTP_NG_PROFILE_STATUS_U; + + +#define _mbg_swab_ptp_ng_profile_status_u( _profile, _p ) \ +do \ +{ \ + switch ( (_profile) ) \ + { \ + case PTP_PRESETS_POWER: \ + _mbg_swab_ptp_ng_c37238_2011_settings( &(_p)->c37238_2011 ); \ + break; \ + \ + case PTP_PRESETS_C37238_2017: \ + _mbg_swab_ptp_ng_c37238_2017_settings( &(_p)->c37238_2017 ); \ + break; \ + \ + case PTP_PRESETS_SMPTE: \ + _mbg_swab_ptp_ng_smpte_20592_status( &(_p)->smpte_20592 ); \ + break; \ + \ + case PTP_PRESETS_TELECOM_PHASE: \ + _mbg_swab_ptp_ng_telecom_g82751_settings( &(_p)->g82751 ); \ + break; \ + \ + default: break; \ + } \ +} while ( 0 ) + + +enum MBG_PTP_NG_INSTC_STATUS_FLAGS +{ + MBG_PTP_NG_INSTC_STATUS_FLAG_STACK_NOT_RUNNING, ///< Indicates, that the PTP stack for this instance is not running + MBG_PTP_NG_INSTC_STATUS_FLAG_M2S_DELAY_VALID, + MBG_PTP_NG_INSTC_STATUS_FLAG_S2M_DELAY_VALID, + + N_MBG_PTP_NG_INSTC_STATUS_FLAGS +}; + + + +enum MBG_PTP_NG_INSTC_STATUS_FLAG_MASKS +{ + MBG_PTP_NG_INSTC_STATUS_FLAG_STACK_NOT_RUNNING_MSK = (1UL << MBG_PTP_NG_INSTC_STATUS_FLAG_STACK_NOT_RUNNING), ///< See ::MBG_PTP_NG_INSTC_STATUS_FLAG_STACK_NOT_RUNNING + MBG_PTP_NG_INSTC_STATUS_FLAG_M2S_DELAY_VALID_MSK = (1UL << MBG_PTP_NG_INSTC_STATUS_FLAG_M2S_DELAY_VALID), ///< See ::MBG_PTP_NG_INSTC_STATUS_FLAG_M2S_DELAY_VALID + MBG_PTP_NG_INSTC_STATUS_FLAG_S2M_DELAY_VALID_MSK = (1UL << MBG_PTP_NG_INSTC_STATUS_FLAG_S2M_DELAY_VALID), ///< See ::MBG_PTP_NG_INSTC_STATUS_FLAG_S2M_DELAY_VALID +}; + + +/** + * @brief A structure used to read the status of a PTP instance + */ +typedef struct mbg_ptp_ng_instc_status_s +{ + MBG_PTP_NG_PKT_STATS m2s_delay; ///< current statistics of the Master to Slave delay + MBG_PTP_NG_PKT_STATS s2m_delay; ///< current statistics of the Slave to Master delay + uint16_t num_uc_slaves; ///< current number of unicast slaves in unicast master mode + uint8_t utilization; ///< current resource utilization (msg/sec) in % + uint8_t profile; ///< Selected PTP preset or profile, see ::PTP_PRESETS. + uint8_t num_atois; ///< number of valid atois status, see #atoi_status + uint8_t protocol; ///< current network protocol, see ::PTP_NW_PROTS + uint8_t reserved_1[2]; ///< reserved, currently always 0 + MBG_PTP_V2_NG_DEFAULT_DATASET default_ds; ///< the default dataset of the PTP instance + MBG_PTP_V2_NG_CURRENT_DATASET current_ds; ///< the current dataset of the PTP instance + MBG_PTP_V2_NG_PARENT_DATASET parent_ds; ///< the parent dataset of the PTP instance + MBG_PTP_V2_NG_TIME_PROPERTIES_DATASET time_properties_ds; ///< the time properties dataset of the PTP instance + MBG_PTP_V2_NG_PORT_DATASET port_ds; ///< the port dataset of the PTP instance + MBG_PTP_NG_PROFILE_STATUS_U profile_status; ///< Union that includes all profile specific parameters; the profile is selected with the #profile parameter. + MBG_PTP_NG_ATOI_STATUS atoi_status[MAX_MBG_PTP_NG_ATOI_STATUS]; ///< current status of available ATOIs + uint32_t flags; ///< See ::MBG_PTP_NG_INSTC_STATUS_FLAG_MASKS + uint32_t reserved_2[3]; ///< reserved, currently always 0 + +} MBG_PTP_NG_INSTC_STATUS; + + +#define _mbg_swab_ptp_ng_instc_status( _p ) \ +{ \ + unsigned i; \ + _mbg_swab_ptp_ng_pkt_stats( &(_p)->m2s_delay ); \ + _mbg_swab_ptp_ng_pkt_stats( &(_p)->s2m_delay ); \ + _mbg_swab16( &(_p)->num_uc_slaves ); \ + _mbg_swab_ptp_v2_ng_default_dataset( &(_p)->default_ds ); \ + _mbg_swab_ptp_v2_ng_current_dataset( &(_p)->current_ds ); \ + _mbg_swab_ptp_v2_ng_parent_dataset( &(_p)->parent_ds ); \ + _mbg_swab_ptp_v2_ng_time_properties_dataset( &(_p)->time_properties_ds ); \ + _mbg_swab_ptp_v2_ng_port_dataset( &(_p)->port_ds ); \ + _mbg_swab_ptp_ng_profile_status_u( (_p)->profile, &(_p)->profile_status ); \ + for ( i = 0; i < MAX_MBG_PTP_NG_ATOI_STATUS; ++i) \ + _mbg_swab_ptp_ng_atoi_status( &(_p)->atoi_status[i] ); \ + _mbg_swab32( &(_p)->flags ); \ +} + + +/** + * @brief + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + + MBG_PTP_NG_INSTC_STATUS status; + +} MBG_PTP_NG_INSTC_STATUS_IDX; + + +#define _mbg_swab_ptp_ng_instc_status_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_instc_status( &(_p)->status ); \ +} + + +typedef struct mbg_ptp_ng_instc_pkt_cntrs_s +{ + uint32_t rx_all; ///< overall Rx packet counter + uint32_t rx_announce; ///< Accepted Announce message Rx counter + uint32_t rx_sync; ///< Accepted Sync message Rx counter + uint32_t rx_follow_up; ///< Accepted Follow-up message Rx counter + uint32_t rx_delay_req; ///< Accepted Delay request message Rx counter + uint32_t rx_delay_resp; ///< Accepted Delay response message Rx counter + uint32_t rx_pdelay_req; ///< Accepted PDelay Request message Rx counter + uint32_t rx_pdelay_resp; ///< Accepted PDelay Response message Rx counter + uint32_t rx_pdelay_follow_up; ///< Accepted PDelay Follow-Up message Rx counter + uint32_t rx_signalling; ///< Accepted Signalling message Rx counter + uint32_t rx_management; ///< Accepted Management message Rx counter + uint32_t rx_management_err; ///< Management error counter (rx) + + uint32_t tx_all; ///< overall Tx packet counter + uint32_t tx_announce; ///< Announce message Tx counter + uint32_t tx_sync; ///< Sync message Tx counter + uint32_t tx_follow_up; ///< Follow-up message Tx counter + uint32_t tx_delay_req; ///< Delay request message Tx counter + uint32_t tx_delay_resp; ///< Delay response message Tx counter + uint32_t tx_pdelay_req; ///< PDelay Request message Tx counter + uint32_t tx_pdelay_resp; ///< PDelay Response message Tx counter + uint32_t tx_pdelay_follow_up; ///< PDelay Follow-Up message Tx counter + uint32_t tx_signalling; ///< Signalling message Tx counter + uint32_t tx_management; ///< Management message Tx counter + uint32_t reserved_1; ///< Reserved, currently always 0 + + uint32_t ann_receipt_timeout; ///< Announce receipt timeout counter + uint32_t reserved_2; ///< Reserved, currently always 0 + + // The following counters (msg/second counter) are represented in + // fixed point format. The lower 8 bit represent digits after the + // radix (comma), the higher 24 bits digits before it. That's a + // scaling factor of 1/(2^8). To display the number in decimal + // notation use: + // printf("%d.%d", rxPerSec >> 8, ((rxPerSec & 0xFF) * 100) >> 8) + uint32_t rx_all_per_sec; ///< overall Rx msg/second + uint32_t rx_announce_per_sec; ///< Accepted Announce msg Rx msg/second + uint32_t rx_sync_per_sec; ///< Accepted Sync msg Rx msg/second + uint32_t rx_follow_up_per_sec; ///< Accepted Follow-up msg Rx msg/second + uint32_t rx_delay_req_per_sec; ///< Accepted Delay request msg Rx msg/second + uint32_t rx_delay_resp_per_sec; ///< Accepted Delay response msg Rx msg/second + uint32_t rx_pdelay_req_per_sec; ///< Accepted PDelay Request msg Rx msg/second + uint32_t rx_pdelay_resp_per_sec; ///< Accepted PDelay Response msg Rx msg/second + uint32_t rx_pdelay_follow_up_per_sec; ///< Accepted PDelay Follow-Up msg Rx msg/sec. + uint32_t rx_signalling_per_sec; ///< Accepted Signalling msg Rx msg/second + uint32_t rx_management_per_sec; ///< Accepted Management msg Rx msg/second + uint32_t reserved_3; ///< Reserved, currently always 0 + + uint32_t tx_all_per_sec; ///< overall Tx msg/second + uint32_t tx_announce_per_sec; ///< Announce msg Tx msg/second + uint32_t tx_sync_per_sec; ///< Sync msg Tx msg/second + uint32_t tx_follow_up_per_sec; ///< Follow-up msg Tx msg/second + uint32_t tx_delay_req_per_sec; ///< Delay request msg Tx msg/second + uint32_t tx_delay_resp_per_sec; ///< Delay response msg Tx msg/second + uint32_t tx_pdelay_req_per_sec; ///< PDelay Request msg Tx msg/second + uint32_t tx_pdelay_resp_per_sec; ///< PDelay Response msg Tx msg/second + uint32_t tx_pdelay_follow_up_per_sec; ///< PDelay Follow-Up msg Tx msg/second + uint32_t tx_signalling_per_sec; ///< Signalling msg Tx msg/second + uint32_t tx_management_per_sec; ///< Management msg Tx msg/second + uint32_t reserved_4; ///< Reserved, currently always 0 + +} MBG_PTP_NG_INSTC_PKT_CNTRS; + + +#define _mbg_swab_ptp_ng_instc_pkt_cntrs( _p ) \ +{ \ + _mbg_swab32( &(_p)->rx_all ); \ + _mbg_swab32( &(_p)->rx_announce ); \ + _mbg_swab32( &(_p)->rx_sync ); \ + _mbg_swab32( &(_p)->rx_follow_up ); \ + _mbg_swab32( &(_p)->rx_delay_req ); \ + _mbg_swab32( &(_p)->rx_delay_resp ); \ + _mbg_swab32( &(_p)->rx_pdelay_req ); \ + _mbg_swab32( &(_p)->rx_pdelay_resp ); \ + _mbg_swab32( &(_p)->rx_pdelay_follow_up ); \ + _mbg_swab32( &(_p)->rx_signalling ); \ + _mbg_swab32( &(_p)->rx_management ); \ + _mbg_swab32( &(_p)->rx_management_err ); \ + \ + _mbg_swab32( &(_p)->tx_all ); \ + _mbg_swab32( &(_p)->tx_announce ); \ + _mbg_swab32( &(_p)->tx_sync ); \ + _mbg_swab32( &(_p)->tx_follow_up ); \ + _mbg_swab32( &(_p)->tx_delay_req ); \ + _mbg_swab32( &(_p)->tx_delay_resp ); \ + _mbg_swab32( &(_p)->tx_pdelay_req ); \ + _mbg_swab32( &(_p)->tx_pdelay_resp ); \ + _mbg_swab32( &(_p)->tx_pdelay_follow_up ); \ + _mbg_swab32( &(_p)->tx_signalling ); \ + _mbg_swab32( &(_p)->tx_management ); \ + \ + _mbg_swab32( &(_p)->ann_receipt_timeout ); \ + \ + _mbg_swab32( &(_p)->rx_all_per_sec ); \ + _mbg_swab32( &(_p)->rx_announce_per_sec ); \ + _mbg_swab32( &(_p)->rx_sync_per_sec ); \ + _mbg_swab32( &(_p)->rx_follow_up_per_sec ); \ + _mbg_swab32( &(_p)->rx_delay_req_per_sec ); \ + _mbg_swab32( &(_p)->rx_delay_resp_per_sec ); \ + _mbg_swab32( &(_p)->rx_pdelay_req_per_sec ); \ + _mbg_swab32( &(_p)->rx_pdelay_resp_per_sec ); \ + _mbg_swab32( &(_p)->rx_pdelay_follow_up_per_sec ); \ + _mbg_swab32( &(_p)->rx_signalling_per_sec ); \ + _mbg_swab32( &(_p)->rx_management_per_sec ); \ + \ + _mbg_swab32( &(_p)->tx_all_per_sec ); \ + _mbg_swab32( &(_p)->tx_announce_per_sec ); \ + _mbg_swab32( &(_p)->tx_sync_per_sec ); \ + _mbg_swab32( &(_p)->tx_follow_up_per_sec ); \ + _mbg_swab32( &(_p)->tx_delay_req_per_sec ); \ + _mbg_swab32( &(_p)->tx_delay_resp_per_sec ); \ + _mbg_swab32( &(_p)->tx_pdelay_req_per_sec ); \ + _mbg_swab32( &(_p)->tx_pdelay_resp_per_sec ); \ + _mbg_swab32( &(_p)->tx_pdelay_follow_up_per_sec ); \ + _mbg_swab32( &(_p)->tx_signalling_per_sec ); \ + _mbg_swab32( &(_p)->tx_management_per_sec ); \ +} + + +/** + * @brief + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + + MBG_PTP_NG_INSTC_PKT_CNTRS cntrs; + +} MBG_PTP_NG_INSTC_PKT_CNTRS_IDX; + + +#define _mbg_swab_ptp_ng_instc_pkt_cntrs_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_instc_pkt_cntrs( &(_p)->cntrs ); \ +} + + +/** + * @brief A structure used to read the status of a unicast slave of an instance running in unicast master mode + * @see ::MBG_PTP_NG_INSTC_STATUS::num_uc_slaves + */ +typedef struct mbg_ptp_ng_uc_slave_status_s +{ + uint8_t addr[IP6_ADDR_BYTES]; ///< IPv4, IPv6 or MAC address + ///< Depending on the appropriate ::MBG_PTP_NG_INSTC_SETTINGS::protocol + + MBG_PTP_NG_INTV_CFG intvs; ///< Granted message intervals + uint32_t ann_duration; ///< Remaining announce message duration + + uint32_t sync_duration; ///< Remaining sync message duration + uint32_t resp_duration; ///< Remaining delay reponse duration + + uint32_t reserved_4[8]; ///< reserved, currently always 0 + +} MBG_PTP_NG_UC_SLAVE_STATUS; + + +#define _mbg_swab_ptp_ng_uc_slave_status( _p ) \ +{ \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs ); \ + _mbg_swab32( &(_p)->ann_duration ); \ + _mbg_swab32( &(_p)->sync_duration ); \ + _mbg_swab32( &(_p)->resp_duration ); \ +} + + +/** + * @brief + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t instc_idx; + + MBG_PTP_NG_UC_SLAVE_STATUS status; + +} MBG_PTP_NG_UC_SLAVE_STATUS_IDX; + + +#define _mbg_swab_ptp_ng_uc_slave_status_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab32( &(_p)->instc_idx ); \ + _mbg_swab_ptp_ng_uc_slave_status( &(_p)->status ); \ +} + + +/** + * @brief Configuration settings specifiying how to query a PTP unicast master + * + * This structure is used on a unicast slave to specify the settings of + * a unicast master polled by the slave. The number of unicast masters + * which can be specified depends on the capabilities of the slave device + * and is returned in ::MBG_PTP_NG_GLB_INFO::max_uc_masters. + */ +typedef struct mbg_ptp_ng_uc_master_settings_s +{ + uint32_t instc_idx; ///< Index of the PTP instance this master belongs to + uint32_t reserved_1; ///< reserved, currently always 0. + + uint8_t grantor_addr[IP6_ADDR_BYTES]; ///< IPv4, IPv6 or MAC address of the grandmaster, depending on + ///< the associated ::MBG_PTP_NG_INSTC_SETTINGS::protocol value. + + PTP_PORT_IDENTITY gm_port_identity; ///< Specified port identity of master port, or ::PTP_CLOCK_ID_WILDCARD and ::PTP_PORT_ID_WILDCARD. + MBG_PTP_NG_INTV_CFG intvs; ///< Intervals to be requested by the Slave instance for this master. + uint16_t message_duration; ///< Subscription period [s]. + + uint32_t reserved_3[4]; ///< Reserved, currently always 0. + +} MBG_PTP_NG_UC_MASTER_SETTINGS; + + +#define _mbg_swab_ptp_ng_uc_master_settings( _p ) \ +{ \ + _mbg_swab32( &(_p)->instc_idx ); \ + _mbg_swab_ptp_port_identity( &(_p)->gm_port_identity ); \ + _mbg_swab_ptp_ng_intv_cfg( &(_p)->intvs ); \ + _mbg_swab16( &(_p)->message_duration ); \ +} + + +/** + * @brief Configuration settings for a specific PTP unicast master + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + + MBG_PTP_NG_UC_MASTER_SETTINGS settings; + +} MBG_PTP_NG_UC_MASTER_SETTINGS_IDX; + + +#define _mbg_swab_ptp_ng_uc_master_settings_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_uc_master_settings( &(_p)->settings ); \ +} + + +/** + * @brief Current settings and general capabilities of a unicast master + * + * This structure is used with a PTP unicast slave device to specify + * a PTP unicast master which can be queried by the slave device. + */ +typedef struct mbg_ptp_ng_uc_master_info_s +{ + MBG_PTP_NG_UC_MASTER_SETTINGS settings; + + uint32_t reserved[4]; ///< reserved, currently always 0 + +} MBG_PTP_NG_UC_MASTER_INFO; + + +#define _mbg_swab_ptp_ng_uc_master_info( _p ) \ +{ \ + _mbg_swab_ptp_ng_uc_master_settings( &(_p)->settings ); \ +} + + +/** + * @brief Current settings and general capabilities of a specific unicast master + * + * This structure is used with a PTP unicast slave device to specify + * a PTP unicast master which can be queried by the slave device. + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + uint32_t reserved; ///< padding for 8-byte alignment, some settings contain int64_t + + MBG_PTP_NG_UC_MASTER_INFO info; + +} MBG_PTP_NG_UC_MASTER_INFO_IDX; + + +#define _mbg_swab_ptp_ng_uc_master_info_idx( _p ) \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ptp_ng_uc_master_info( &(_p)->info ); \ +} + + +/** @} defgroup group_ptp_ng */ + /** @} defgroup group_ptp */ @@ -9190,38 +18008,51 @@ enum NTP_ROLES */ enum NTP_ROLE_MASKS { - NTP_MSK_ROLE_NONE = ( 1UL << NTP_ROLE_NONE ), ///< see ::NTP_ROLE_NONE - NTP_MSK_ROLE_CLIENT = ( 1UL << NTP_ROLE_CLIENT ), ///< see ::NTP_ROLE_CLIENT - NTP_MSK_ROLE_SERVER = ( 1UL << NTP_ROLE_SERVER ), ///< see ::NTP_ROLE_SERVER - NTP_MSK_ROLE_CLIENT_SERVER = ( 1UL << NTP_ROLE_CLIENT_SERVER ), ///< see ::NTP_ROLE_CLIENT_SERVER + NTP_MSK_ROLE_NONE = ( 1UL << NTP_ROLE_NONE ), ///< See ::NTP_ROLE_NONE + NTP_MSK_ROLE_CLIENT = ( 1UL << NTP_ROLE_CLIENT ), ///< See ::NTP_ROLE_CLIENT + NTP_MSK_ROLE_SERVER = ( 1UL << NTP_ROLE_SERVER ), ///< See ::NTP_ROLE_SERVER + NTP_MSK_ROLE_CLIENT_SERVER = ( 1UL << NTP_ROLE_CLIENT_SERVER ), ///< See ::NTP_ROLE_CLIENT_SERVER }; /** * @brief Enumeration of global NTP flags * - * @see ::NTP_FLAG_MASKS + * @see @ref NTP_FLAG_MASKS */ enum NTP_FLAGS { - NTP_IPV4, ///< NTP via IPv4/UDP - NTP_IPV6, ///< NTP via IPv6/UDP - NTP_SYMM_KEYS, ///< support symmetric key authentication (MD5) - NTP_AUTOKEY, ///< include authentication fields encrypted using the autokey scheme - NTP_BURST, ///< send a burst of eight packets at each polling cycle - NTP_IBURST, ///< send a burst of eight packets at the first polling cycle - NTP_NO_SELECT, ///< marks a server as not to be selected for time synchronization - NTP_PREEMPT, ///< specifies the association as preemptable rather than the default persistent - NTP_PREFER, ///< marks a server as preferred peer for time synchronization - NTP_TRUE, ///< force the association to assume truechimer status; always survive the selection and clustering algorithms - NTP_BROADCAST, ///< transmission via broadcast, point to multipoint - NTP_MULTICAST, ///< transmission via multicast, point to multipoint - NTP_MANYCAST, ///< transmission via manycast, point to multipoint - NTP_POOL, ///< peer shall be treated as a pool server + NTP_IPV4, ///< NTP via IPv4/UDP + NTP_IPV6, ///< NTP via IPv6/UDP + NTP_SYMM_KEYS, ///< support symmetric key authentication (MD5) + NTP_AUTOKEY, ///< include authentication fields encrypted using the autokey scheme + NTP_BURST, ///< send a burst of eight packets at each polling cycle + NTP_IBURST, ///< send a burst of eight packets at the first polling cycle + NTP_NO_SELECT, ///< marks a server as not to be selected for time synchronization + NTP_PREEMPT, ///< specifies the association as preemptable rather than the default persistent + NTP_PREFER, ///< marks a server as preferred peer for time synchronization + NTP_TRUE, ///< force the association to assume truechimer status; always survive the selection and clustering algorithms + NTP_BROADCAST, ///< transmission via broadcast, point to multipoint + NTP_MULTICAST, ///< transmission via multicast, point to multipoint + NTP_MANYCAST, ///< transmission via manycast, point to multipoint + NTP_POOL, ///< peer shall be treated as a pool server + NTP_PEER, ///< specifies a symmetric-active association should be used with this server + NTP_BROADCASTCLIENT, ///< receive broadcast messages on all interfaces + NTP_MULTICASTCLIENT, ///< receive messages from the given multicast group + NTP_MANYCASTCLIENT, ///< manycast shall be used on the given multicast address to discover peers + NTP_RESTRICTIONS, ///< NTP supports restrictions + NTP_DISCARD, ///< NTP supports "discard" rate limiting + NTP_REFCLOCKS, ///< NTP supports refclocks + NTP_STATISTICS, ///< NTP supports statistics (e.g. clockstats, loopstats, etc...) + NTP_MISCELLANEOUS, ///< NTP supports misc options (e.g. tinker, driftfile, orphan mode, etc...) + NTP_TRUSTED_KEYS, ///< NTP supports specifying trusted symmetric keys + NTP_FIXED_REFCLOCKS, ///< NTP refclocks not configurable + NTP_ADD_CONF, ///< Supports additional NTP configuration (i.e. via script) N_NTP_FLAGS }; + /** * @brief Flag masks associated with ::NTP_FLAGS * @@ -9232,24 +18063,42 @@ enum NTP_FLAGS * @todo We may need structures to configure symmetric keys, and autokey certificates. * * @see ::NTP_FLAGS - */ -enum NTP_FLAG_MASKS -{ - NTP_MSK_IPV4 = ( 1UL << NTP_IPV4 ), ///< see ::NTP_IPV4 - NTP_MSK_IPV6 = ( 1UL << NTP_IPV6 ), ///< see ::NTP_IPV6 - NTP_MSK_SYMM_KEYS = ( 1UL << NTP_SYMM_KEYS ), ///< see ::NTP_SYMM_KEYS - NTP_MSK_AUTOKEY = ( 1UL << NTP_AUTOKEY ), ///< see ::NTP_AUTOKEY - NTP_MSK_BURST = ( 1UL << NTP_BURST ), ///< see ::NTP_BURST - NTP_MSK_IBURST = ( 1UL << NTP_IBURST ), ///< see ::NTP_IBURST - NTP_MSK_NO_SELECT = ( 1UL << NTP_NO_SELECT ), ///< see ::NTP_NO_SELECT - NTP_MSK_PREEMPT = ( 1UL << NTP_PREEMPT ), ///< see ::NTP_PREEMPT - NTP_MSK_PREFER = ( 1UL << NTP_PREFER ), ///< see ::NTP_PREFER - NTP_MSK_TRUE = ( 1UL << NTP_TRUE ), ///< see ::NTP_TRUE - NTP_MSK_BROADCAST = ( 1UL << NTP_BROADCAST ), ///< see ::NTP_BROADCAST - NTP_MSK_MULTICAST = ( 1UL << NTP_MULTICAST ), ///< see ::NTP_MULTICAST - NTP_MSK_MANYCAST = ( 1UL << NTP_MANYCAST ), ///< see ::NTP_MANYCAST - NTP_MSK_POOL = ( 1UL << NTP_POOL ) ///< see ::NTP_POOL -}; + * + * @anchor NTP_FLAG_MASKS @{ */ + +#define NTP_MSK_IPV4 ( 1UL << NTP_IPV4 ) ///< See ::NTP_IPV4 +#define NTP_MSK_IPV6 ( 1UL << NTP_IPV6 ) ///< See ::NTP_IPV6 +#define NTP_MSK_SYMM_KEYS ( 1UL << NTP_SYMM_KEYS ) ///< See ::NTP_SYMM_KEYS; if set, ::NTP_SYMM_KEY_LIMITS can be queried +#define NTP_MSK_AUTOKEY ( 1UL << NTP_AUTOKEY ) ///< See ::NTP_AUTOKEY +#define NTP_MSK_BURST ( 1UL << NTP_BURST ) ///< See ::NTP_BURST +#define NTP_MSK_IBURST ( 1UL << NTP_IBURST ) ///< See ::NTP_IBURST +#define NTP_MSK_NO_SELECT ( 1UL << NTP_NO_SELECT ) ///< See ::NTP_NO_SELECT +#define NTP_MSK_PREEMPT ( 1UL << NTP_PREEMPT ) ///< See ::NTP_PREEMPT +#define NTP_MSK_PREFER ( 1UL << NTP_PREFER ) ///< See ::NTP_PREFER +#define NTP_MSK_TRUE ( 1UL << NTP_TRUE ) ///< See ::NTP_TRUE +#define NTP_MSK_BROADCAST ( 1UL << NTP_BROADCAST ) ///< See ::NTP_BROADCAST +#define NTP_MSK_MULTICAST ( 1UL << NTP_MULTICAST ) ///< See ::NTP_MULTICAST +#define NTP_MSK_MANYCAST ( 1UL << NTP_MANYCAST ) ///< See ::NTP_MANYCAST +#define NTP_MSK_POOL ( 1UL << NTP_POOL ) ///< See ::NTP_POOL +#define NTP_MSK_PEER ( 1UL << NTP_PEER ) ///< See ::NTP_PEER +#define NTP_MSK_BROADCASTCLIENT ( 1UL << NTP_BROADCASTCLIENT) ///< See ::NTP_BROADCASTCLIENT +#define NTP_MSK_MULTICASTCLIENT ( 1UL << NTP_MULTICASTCLIENT) ///< See ::NTP_MULTICASTCLIENT +#define NTP_MSK_MANYCASTCLIENT ( 1UL << NTP_MANYCASTCLIENT) ///< See ::NTP_MANYCASTCLIENT +#define NTP_MSK_RESTRICTIONS ( 1UL << NTP_RESTRICTIONS ) ///< See ::NTP_RESTRICTIONS +#define NTP_MSK_DISCARD ( 1UL << NTP_DISCARD ) ///< See ::NTP_DISCARD +#define NTP_MSK_REFCLOCKS ( 1UL << NTP_REFCLOCKS ) ///< See ::NTP_REFCLOCKS +#define NTP_MSK_STATISTICS ( 1UL << NTP_STATISTICS ) ///< See ::NTP_STATISTICS; if set, ::NTP_STATS_GLB_INFO can be queried +#define NTP_MSK_MISCELLANEOUS ( 1UL << NTP_MISCELLANEOUS ) ///< See ::NTP_MISCELLANEOUS +#define NTP_MSK_TRUSTED_KEYS ( 1UL << NTP_TRUSTED_KEYS ) ///< See ::NTP_TRUSTED_KEYS +#define NTP_MSK_FIXED_REFCLOCKS ( 1UL << NTP_FIXED_REFCLOCKS ) ///< See ::NTP_FIXED_REFCLOCKS +#define NTP_MSK_ADD_CONF ( 1UL << NTP_ADD_CONF ) ///< See ::NTP_ADD_CONF +/** @} anchor NTP_FLAG_MASKS */ + + +#define NTP_DEF_ADD_CONF_PATH "/etc/mbg" +#define NTP_DEF_ADD_CONF_FILENAME "ntp.conf.add" +#define NTP_DEF_ADD_CONF_FILE NTP_DEF_ADD_CONF_PATH "/" NTP_DEF_ADD_CONF_FILENAME + /** @@ -9259,25 +18108,23 @@ enum NTP_FLAG_MASKS */ typedef struct { - uint8_t ntp_role; ///< one of the supported NTP roles, see ::NTP_ROLES - uint8_t reserved_1; ///< reserved, currently 0 - uint16_t reserved_2; ///< reserved, currently 0 + uint8_t ntp_role; ///< one of the supported NTP roles, see ::NTP_ROLES + uint8_t num_symm_keys; ///< number of configured symm keys + uint8_t num_trusted_keys; ///< number of activated symm keys + uint8_t reserved_1; ///< reserved, currently 0 - uint32_t reserved_3; ///< reserved, currently 0 - uint32_t reserved_4; ///< reserved, currently 0 + uint32_t reserved_2; ///< reserved, currently 0 + uint32_t reserved_3; ///< reserved, currently 0 - uint32_t flags; ///< NTP flags, see ::NTP_FLAG_MASKS + uint32_t flags; ///< NTP flags, see @ref NTP_FLAG_MASKS } NTP_GLB_SETTINGS; #define _mbg_swab_ntp_glb_settings( _p ) \ +do \ { \ - _mbg_swab16( &(_p)->reserved_2 ); \ - _mbg_swab32( &(_p)->reserved_3 ); \ - _mbg_swab32( &(_p)->reserved_4 ); \ - _mbg_swab32( &(_p)->cfg_flags ); \ -} - + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) /** @@ -9289,24 +18136,1003 @@ typedef struct { NTP_GLB_SETTINGS settings; ///< current configuration settings - uint32_t reserved_1; ///< reserved, currently 0 - uint32_t reserved_2; ///< reserved, currently 0 + uint8_t max_symm_keys; ///< number of available symm keys that can be generated, see ::NTP_SYMM_KEY_INFO_IDX + uint8_t max_trusted_keys; ///< number of available trusted keys, see ::NTP_TRUSTED_KEY_INFO_IDX + + uint16_t reserved_2; ///< reserved, currently 0 + uint32_t reserved_3; ///< reserved, currently 0 uint32_t supp_ntp_roles; ///< supported NTP roles, see ::NTP_ROLE_MASKS - uint32_t supp_flags; ///< supported NTP flags, see ::NTP_FLAG_MASKS + uint32_t supp_flags; ///< supported NTP flags, see @ref NTP_FLAG_MASKS } NTP_GLB_INFO; #define _mbg_swab_ntp_glb_info( _p ) \ +do \ { \ _mbg_swab_ntp_glb_settings( &(_p)->settings ); \ - _mbg_swab32( &(_p)->reserved_1 ); \ - _mbg_swab32( &(_p)->reserved_2 ); \ _mbg_swab32( &(_p)->supp_ntp_roles ); \ _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +#if defined( _PRELIMINARY_CODE ) + +/** + * @brief Enumeration of supported NTP restriction types/keywords + * + * Used with ::NTP_RESTR::type + * + * @see https://www.eecis.udel.edu/~mills/ntp/html/accopt.html#restrict + * @see ::NTP_RESTR_TYPE_MSKS + */ +enum NTP_RESTR_TYPES +{ + NTP_RESTR_TYPE_DEFAULT, + NTP_RESTR_TYPE_SOURCE, + NTP_RESTR_TYPE_ADDRESS, + N_NTP_RESTR_TYPES +}; + + + +/** + * @brief Bit masks associated with ::NTP_RESTR_TYPES + * + * Used with ::NTP_RESTR_LIMITS::supp_types + * + * @see ::NTP_RESTR_TYPES + */ +enum NTP_RESTR_TYPE_MSKS +{ + NTP_RESTR_TYPE_MSK_DEFAULT = ( 1UL << NTP_RESTR_TYPE_DEFAULT ), ///< See ::NTP_RESTR_TYPE_DEFAULT + NTP_RESTR_TYPE_MSK_SOURCE = ( 1UL << NTP_RESTR_TYPE_SOURCE ), ///< See ::NTP_RESTR_TYPE_SOURCE + NTP_RESTR_TYPE_MSK_ADDRESS = ( 1UL << NTP_RESTR_TYPE_ADDRESS ) ///< See ::NTP_RESTR_TYPE_ADDRESS +}; + + + +/** + * @brief Enumeration of supported NTP restriction flags + * + * Used to define ::NTP_RESTR_FLAG_MSKS + * + * @see https://www.eecis.udel.edu/~mills/ntp/html/accopt.html#restrict + * @see ::NTP_RESTR_FLAG_MSKS + */ +enum NTP_RESTR_FLAGS +{ + NTP_RESTR_FLAG_FLAKE, + NTP_RESTR_FLAG_IGNORE, + NTP_RESTR_FLAG_KOD, + NTP_RESTR_FLAG_LIMITED, + NTP_RESTR_FLAG_LOWPRIOTRAP, + NTP_RESTR_FLAG_MSSNTP, + NTP_RESTR_FLAG_NOMODIFY, + NTP_RESTR_FLAG_NOQUERY, + NTP_RESTR_FLAG_NOPEER, + NTP_RESTR_FLAG_NOSERVE, + NTP_RESTR_FLAG_NOTRAP, + NTP_RESTR_FLAG_NOTRUST, + NTP_RESTR_FLAG_NTPPORT, + NTP_RESTR_FLAG_VERSION, + NTP_RESTR_FLAG_IPV4, ///< This default restriction only applies to IPv4 + NTP_RESTR_FLAG_IPV6, ///< This default restriction only applies to IPv6 + N_NTP_RESTR_FLAGS +}; + + + +/** + * @brief Flag masks associated with ::NTP_RESTR_FLAGS + * + * Used with ::NTP_RESTR::flags and ::NTP_RESTR_LIMITS::supp_flags + * + * @see ::NTP_RESTR_FLAGS + */ +enum NTP_RESTR_FLAG_MSKS +{ + NTP_RESTR_FLAG_MSK_FLAKE = ( 1UL << NTP_RESTR_FLAG_FLAKE ), ///< See ::NTP_RESTR_FLAG_FLAKE + NTP_RESTR_FLAG_MSK_IGNORE = ( 1UL << NTP_RESTR_FLAG_IGNORE ), ///< See ::NTP_RESTR_FLAG_IGNORE + NTP_RESTR_FLAG_MSK_KOD = ( 1UL << NTP_RESTR_FLAG_KOD ), ///< See ::NTP_RESTR_FLAG_KOD + NTP_RESTR_FLAG_MSK_LIMITED = ( 1UL << NTP_RESTR_FLAG_LIMITED ), ///< See ::NTP_RESTR_FLAG_LIMITED + NTP_RESTR_FLAG_MSK_LOWPRIOTRAP = ( 1UL << NTP_RESTR_FLAG_LOWPRIOTRAP ),///< See ::NTP_RESTR_FLAG_LOWPRIOTRAP + NTP_RESTR_FLAG_MSK_MSSNTP = ( 1UL << NTP_RESTR_FLAG_MSSNTP ), ///< See ::NTP_RESTR_FLAG_MSSNTP + NTP_RESTR_FLAG_MSK_NOMODIFY = ( 1UL << NTP_RESTR_FLAG_NOMODIFY ), ///< See ::NTP_RESTR_FLAG_NOMODIFY + NTP_RESTR_FLAG_MSK_NOQUERY = ( 1UL << NTP_RESTR_FLAG_NOQUERY ), ///< See ::NTP_RESTR_FLAG_NOQUERY + NTP_RESTR_FLAG_MSK_NOPEER = ( 1UL << NTP_RESTR_FLAG_NOPEER ), ///< See ::NTP_RESTR_FLAG_NOPEER + NTP_RESTR_FLAG_MSK_NOSERVE = ( 1UL << NTP_RESTR_FLAG_NOSERVE ), ///< See ::NTP_RESTR_FLAG_NOSERVE + NTP_RESTR_FLAG_MSK_NOTRAP = ( 1UL << NTP_RESTR_FLAG_NOTRAP ), ///< See ::NTP_RESTR_FLAG_NOTRAP + NTP_RESTR_FLAG_MSK_NOTRUST = ( 1UL << NTP_RESTR_FLAG_NOTRUST ), ///< See ::NTP_RESTR_FLAG_NOTRUST + NTP_RESTR_FLAG_MSK_NTPPORT = ( 1UL << NTP_RESTR_FLAG_NTPPORT ), ///< See ::NTP_RESTR_FLAG_NTPPORT + NTP_RESTR_FLAG_MSK_VERSION = ( 1UL << NTP_RESTR_FLAG_VERSION ), ///< See ::NTP_RESTR_FLAG_VERSION + NTP_RESTR_FLAG_MSK_IPV4 = ( 1UL << NTP_RESTR_FLAG_IPV4 ), ///< See ::NTP_RESTR_FLAG_IPV4 + NTP_RESTR_FLAG_MSK_IPV6 = ( 1UL << NTP_RESTR_FLAG_IPV6 ) ///< See ::NTP_RESTR_FLAG_IPV6 +}; + + + +/** + * @brief General NTP restriction limits to be read from a device + * + * Used to query from a device how many NTP restrictions are supported + * by the device, then index 0..::NTP_RESTR_LIMITS::cur_restrs-1 + * restriction records can be read from a device. A maximum of + * ::NTP_RESTR_LIMITS::max_restrs can be configured at all. + */ +typedef struct +{ + uint16_t max_restrs; ///< Number of maximum supported restrictions + uint16_t cur_restrs; ///< Number of currently configured restrictions + uint32_t supp_types; ///< Supported restriction types, see ::NTP_RESTR_TYPE_MSKS + uint32_t supp_flags; ///< Supported restriction flags, see ::NTP_RESTR_FLAG_MSKS + uint32_t reserved; ///< Future use + +} NTP_RESTR_LIMITS; + +#define _mbg_swab_ntp_restr_limits( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->max_restrs ); \ + _mbg_swab16( &(_p)->cur_restrs ); \ + _mbg_swab32( &(_p)->supp_types ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + +/** + * @brief NTP restriction + * + * Structure contains all flags and information needed for a valid NTP restriction + * as described in the manual pages at ntp.org. + */ +typedef struct +{ + uint8_t type; ///< Restriction type, see ::NTP_RESTR_TYPES + uint8_t reserved_1; ///< Future use + uint16_t reserved_2; ///< Future use + uint32_t flags; ///< Restriction flags, see ::NTP_RESTR_FLAG_MSKS + + MBG_HOSTNAME addr; ///< Used if ::NTP_RESTR::type == ::NTP_RESTR_TYPE_ADDRESS. + ///< Can contain a hostname, or an IPv4 or IPv6 address + ///< with or without CIDR extension (e.g. 172.16.0.0/16). +} NTP_RESTR; + +#define _mbg_swab_ntp_restr( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab_ntp_restr_discard( &(_p)->u.discard ); \ +} while ( 0 ) + + + +/** + * @brief NTP restriction, plus index + * + * @see ::NTP_RESTR + */ +typedef struct +{ + uint32_t idx; + NTP_RESTR restr; + +} NTP_RESTR_IDX; + +#define _mbg_swab_ntp_restr_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_restr( &(_p)->restr ); \ +} while ( 0 ) + + + +/** + * @brief General NTP "discard" rate limiting limits to be read from a device + * + * Used to query from a device what range of values is supported + * for the NTP "discard" rate limiting configuration. + */ +typedef struct +{ + uint8_t avg_min; ///< Minimum value for avg + uint8_t avg_max; ///< Maximum value for avg + uint8_t min_min; ///< Minimum value for min + uint8_t min_max; ///< Maximum value for min + uint16_t monitor_min; ///< Maximum value for min + uint16_t monitor_max; ///< Maximum value for min + + uint32_t reserved; ///< Future use + +} NTP_DISCARD_LIMITS; + +#define _mbg_swab_ntp_discard_limits( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->monitor_min ); \ + _mbg_swab16( &(_p)->monitor_max ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + + + +/** + * @brief NTP "discard" rate limiting settings as described at ntp.org. + */ +typedef struct +{ + uint8_t avg; ///< Specify the minimum average interpacket spacing in log2 s. + uint8_t min; ///< Specify the minimum interpacket spacing (guard time) in seconds. + uint16_t monitor; ///< ### TODO Which is the unit of this field? + uint32_t reserved; ///< Possible future use + +} NTP_DISCARD_SETTINGS; + +#define _mbg_swab_ntp_discard_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->monitor ); \ + _mbg_swab32( &(_p)->reserved ); \ +} while ( 0 ) + + +/** + * @brief Enumeration of NTP supported statistics + * + * @see ::NTP_GLB_STATS_MASKS + */ +enum NTP_GLB_STATS_FLAGS +{ + NTP_GLB_STATS_FLAG_ENABLE, ///< NTP stats can generally be enabled or disabled + NTP_GLB_STATS_FLAG_CLOCKSTATS, ///< NTP supports clockstats + NTP_GLB_STATS_FLAG_CRYPTOSTATS, ///< NTP supports cryptostats + NTP_GLB_STATS_FLAG_LOOPSTATS, ///< NTP supports loopstats + NTP_GLB_STATS_FLAG_PEERSTATS, ///< NTP supports peerstats + NTP_GLB_STATS_FLAG_RAWSTATS, ///< NTP supports rawstats + NTP_GLB_STATS_FLAG_SYSSTATS, ///< NTP supports sysstats + NTP_GLB_STATS_FLAG_FILEGEN, ///< NTP supports sets of files + ///< If flag is set there are structures needed + ///< that are not avail right now. Future use + N_NTP_GLB_STATS_FLAGS +}; + + + +/** + * @brief Flag masks associated with ::NTP_GLB_STATS_FLAGS + * + * @see ::NTP_GLB_STATS_FLAGS + */ +enum NTP_GLB_STATS_MASKS +{ + NTP_GLB_STATS_MSK_ENABLE = ( 1UL << NTP_GLB_STATS_FLAG_ENABLE ), ///< See ::NTP_GLB_STATS_FLAG_ENABLE + NTP_GLB_STATS_MSK_CLOCKSTATS = ( 1UL << NTP_GLB_STATS_FLAG_CLOCKSTATS ), ///< See ::NTP_GLB_STATS_FLAG_CLOCKSTATS + NTP_GLB_STATS_MSK_CRYPTOSTATS = ( 1UL << NTP_GLB_STATS_FLAG_CRYPTOSTATS ), ///< See ::NTP_GLB_STATS_FLAG_CRYPTOSTATS + NTP_GLB_STATS_MSK_LOOPSTATS = ( 1UL << NTP_GLB_STATS_FLAG_LOOPSTATS ), ///< See ::NTP_GLB_STATS_FLAG_LOOPSTATS + NTP_GLB_STATS_MSK_PEERSTATS = ( 1UL << NTP_GLB_STATS_FLAG_PEERSTATS ), ///< See ::NTP_GLB_STATS_FLAG_PEERSTATS + NTP_GLB_STATS_MSK_RAWSTATS = ( 1UL << NTP_GLB_STATS_FLAG_RAWSTATS ), ///< See ::NTP_GLB_STATS_FLAG_RAWSTATS + NTP_GLB_STATS_MSK_SYSSTATS = ( 1UL << NTP_GLB_STATS_FLAG_SYSSTATS ), ///< See ::NTP_GLB_STATS_FLAG_SYSSTATS + NTP_GLB_STATS_MSK_FILEGEN = ( 1UL << NTP_GLB_STATS_FLAG_FILEGEN ) ///< See ::NTP_GLB_STATS_FLAG_FILEGEN +}; + + + +/** + * @brief Global NTP statistics settings to be read from / written to a device + * + * ::NTP_GLB_STATS_MSK_ENABLE is the switch to enable / disable statistics in + * general. In case the bit is set all other bits stand for special statistic + * types that can be enabled or disabled by setting or deleting its specific bit. + */ +typedef struct +{ + uint32_t flags; ///< See ::NTP_GLB_STATS_MASKS + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + +} NTP_STATS_GLB_SETTINGS; + +#define _mbg_swab_ntp_stats_glb_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + +/** + * @brief NTP statistics settings + * + * This structure can be used to determine possible NTP statistic options + * and can be queried if ::NTP_MSK_STATISTICS bit is set in ::NTP_GLB_INFO::supp_flags. + */ +typedef struct +{ + NTP_STATS_GLB_SETTINGS settings; ///< See ::NTP_STATS_GLB_SETTINGS + + uint32_t supp_stats; ///< See ::NTP_GLB_STATS_MASKS + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + +} NTP_STATS_GLB_INFO; + +#define _mbg_swab_ntp_stats_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_stats_glb_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_stats ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + +#else // !defined( _PRELIMINARY_CODE ), dummy declarations + + typedef int NTP_RESTR_LIMITS; + typedef int NTP_RESTR; + typedef int NTP_RESTR_IDX; + typedef int NTP_DISCARD_LIMITS; + typedef int NTP_DISCARD_SETTINGS; + typedef int NTP_STATS_GLB_SETTINGS; + typedef int NTP_STATS_GLB_INFO; + +#endif // defined( _PRELIMINARY_CODE ) + + +/** + * @brief Enumeration of supported refclock types + * + * Used with ::NTP_REFCLK_CFG_SETTINGS::type + * + * @see https://www.eecis.udel.edu/~mills/ntp/html/refclock.html + * @see ::NTP_REFCLK_TYPE_MSKS + */ +enum NTP_REFCLK_TYPES +{ + NTP_REFCLK_TYPE_LOCAL, ///< NTP local clock + NTP_REFCLK_TYPE_TRUETIME, ///< NTP Truetime driver + NTP_REFCLK_TYPE_PARSE, ///< NTP parse driver + NTP_REFCLK_TYPE_NMEA, ///< NTP NMEA driver + NTP_REFCLK_TYPE_PPS, ///< NTP atom driver (standalone PPS) + NTP_REFCLK_TYPE_SHM, ///< NTP shared memory driver + N_NTP_REFCLK_TYPES +}; + + + +/** + * @brief Bit masks associated with ::NTP_REFCLK_TYPES + * + * Used with ::NTP_REFCLK_CFG_INFO::supp_refclk_types + * + * @see ::NTP_REFCLK_TYPES + */ +enum NTP_REFCLK_TYPE_MSKS +{ + NTP_REFCLK_TYPE_MSK_LOCAL = ( 1UL << NTP_REFCLK_TYPE_LOCAL ), ///< See ::NTP_REFCLK_TYPE_LOCAL + NTP_REFCLK_TYPE_MSK_TRUETIME = ( 1UL << NTP_REFCLK_TYPE_TRUETIME ), ///< See ::NTP_REFCLK_TYPE_TRUETIME + NTP_REFCLK_TYPE_MSK_PARSE = ( 1UL << NTP_REFCLK_TYPE_PARSE ), ///< See ::NTP_REFCLK_TYPE_PARSE + NTP_REFCLK_TYPE_MSK_NMEA = ( 1UL << NTP_REFCLK_TYPE_NMEA ), ///< See ::NTP_REFCLK_TYPE_NMEA + NTP_REFCLK_TYPE_MSK_PPS = ( 1UL << NTP_REFCLK_TYPE_PPS ), ///< See ::NTP_REFCLK_TYPE_PPS + NTP_REFCLK_TYPE_MSK_SHM = ( 1UL << NTP_REFCLK_TYPE_SHM ) ///< See ::NTP_REFCLK_TYPE_SHM +}; + + +/** + * @brief Numbers related to the "fudge" flags used with ntpd's refclock interface. + * + * Used with ::NTP_REFCLK_CFG_SETTINGS::drv_flags_enable + * and ::NTP_REFCLK_CFG_SETTINGS::drv_flags_value. + * + * The refclock interface provided by @a ntpd supports a number of flags + * (flag1..flag4) which can be "fudged" in @a ntp.conf to control specific + * features of a particular refclock driver, e.g.: + * "fudge 127.127.8.0 flag1 1" + * + * Which feature is controlled by which flag depends on the refclock + * driver type, so usually each flag has a different meaning for + * different refclock types. + * + * There are different cases to be distinguished: + * + * - If a flag is not specified at all in @a ntp.conf then + * the controlled feature is enabled or disabled + * according to the driver's default settings. + * + * - If a flag is specified as '0' or '1' in @a ntp.conf then + * the controlled feature is enabled or disabled + * according to the value of the flag. + * + * Thus, the bit mask in ::NTP_REFCLK_CFG_SETTINGS::drv_flags_enable + * controls if the associated fudge flag should be specified in ntp.conf, + * and if it is specified then the associated bit in + * ::NTP_REFCLK_CFG_SETTINGS::drv_flags_value controls if the fudge flag + * is set to 0 or 1. + * + * @anchor NTP_FUDGE_FLAG_NUMBERS @{ */ + +#define NTP_MIN_REFCLOCK_FUDGE_FLAG 1 ///< minimum refclock fudge flag number, associated with bit 0 +#define N_NTP_REFCLOCK_FUDGE_FLAGS 4 ///< the number of supported fudge flags + +/** @} anchor NTP_FUDGE_FLAG_NUMBERS */ + + +/** + * @brief NTP refclock specific settings + * + * Used to configure a NTP refclock. + */ +typedef struct +{ + uint8_t type; ///< See ::NTP_REFCLK_TYPES + uint8_t instance; ///< Refclock instance of the specified type. Usually up to 4 instances of the same type are supported by ntpd. + uint8_t mode; ///< Driver specific "mode" ::FIXME Flag to enable "mode"? + int8_t stratum; ///< Stratum number to be fudged; -1 if unspecified and thus default is to be used + + int8_t refid[4]; ///< Reference id used by driver ::FIXME Flag to enable "refid"? + + uint8_t minpoll; ///< Minimum polling interval, [log2 seconds], 0 if unused/unspecified + uint8_t maxpoll; ///< Maximum polling interval, [log2 seconds], 0 if unused/unspecified + uint8_t reserved_1; ///< Future use + uint8_t reserved_2; ///< Future use + + NANO_TIME_64 time1; ///< Driver specific + NANO_TIME_64 time2; ///< Driver specific + + uint16_t drv_flags_enable; ///< Enable/disable driver specific flags, see @ref NTP_FUDGE_FLAG_NUMBERS + uint16_t drv_flags_value; ///< 0 or 1, if (drv_flags_enable & x) == 1, see @ref NTP_FUDGE_FLAG_NUMBERS + + uint32_t flags; ///< See @ref NTP_FLAG_MASKS. Only flags specified in ::FIXME can be used here. + + uint32_t reserved_3; ///< Future use + +} NTP_REFCLK_CFG_SETTINGS; + +#define _mbg_swab_ntp_refclk_cfg_settings( _p ) \ +do \ +{ \ + _mbg_swab_nano_time_64( &(_p)->time1 ); \ + _mbg_swab_nano_time_64( &(_p)->time2 ); \ + _mbg_swab16( &(_p)->drv_flags_enable ); \ + _mbg_swab16( &(_p)->drv_flags_value ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief NTP refclock settings index + * + * @see ::NTP_REFCLK_CFG_SETTINGS + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + NTP_REFCLK_CFG_SETTINGS settings; ///< See ::NTP_REFCLK_CFG_SETTINGS + +} NTP_REFCLK_CFG_SETTINGS_IDX; + +#define _mbg_swab_ntp_refclk_cfg_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_refclk_cfg_settings( &(_p)->settings ); \ +} while ( 0 ) + +/** + * @brief Enumeration of NTP refclock config flags + * + * @see @ref NTP_REFCLK_CFG_FLAGS + */ +enum NTP_REFCLK_CFG_FLAGS +{ + NTP_REFCLK_CFG_TRUSTTIME, ///< Trusttime of refclk configurable + + N_NTP_REFCLK_CFG_FLAGS +}; + + +/** + * @brief Flag masks associated with ::NTP_REFCLK_CFG_FLAGS + * + * Used with ::NTP_REFCLK_CFG_INFO::supp_cfgs, + * + * @see ::NTP_REFCLK_CFG_FLAGS + * + * @anchor NTP_REFCLK_CFG_FLAGS_MASKS @{ */ + +#define NTP_MSK_REFCLK_CFG_TRUSTTIME ( 1UL << NTP_REFCLK_CFG_TRUSTTIME ) ///< See ::NTP_REFCLK_CFG_TRUSTTIME + + +/** @} anchor NTP_REFCLK_CFG_FLAGS_MASKS */ + +/** + * @brief NTP refclock configuration and supported refclock types + * + * This structure can be used to set an NTP refclock configuration + * and get to know its overall supported refclocks. + */ +typedef struct +{ + NTP_REFCLK_CFG_SETTINGS settings; ///< See ::NTP_REFCLK_CFG_SETTINGS + + uint8_t supp_cfgs; ///< See @ref NTP_REFCLK_CFG_FLAGS + uint8_t reserved; ///< Future use + uint16_t supp_refclk_types; ///< See ::NTP_REFCLK_TYPE_MSKS + +} NTP_REFCLK_CFG_INFO; + +#define _mbg_swab_ntp_refclk_cfg_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_refclk_cfg_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_refclk_types ); \ +} while ( 0 ) + + + +/** + * @brief NTP refclock info, with index + * + * @see ::NTP_REFCLK_CFG_INFO + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + NTP_REFCLK_CFG_INFO info; + +} NTP_REFCLK_CFG_INFO_IDX; + +#define _mbg_swab_ntp_refclk_cfg_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_refclk_cfg_info( &(_p)->info ); \ +} while ( 0 ) + + +enum NTP_SYMM_KEY_FLAGS +{ + NTP_SYMM_KEY_WHITELIST, ///< The device supports whitelisting for symmetric keys + N_NTP_SYMM_KEY_FLAGS +}; + + +enum NTP_SYMM_KEY_FLAG_MASKS +{ + NTP_SYMM_KEY_WHITELIST_MSK = ( 1UL << NTP_SYMM_KEY_WHITELIST ) ///< See ::NTP_SYMM_KEY_WHITELIST +}; + + +/** + * @brief Enumeration of NTP supported symmetric key hashing algorithms + * + * @see ::NTP_SYMM_KEY_HASH_MASKS + * + * @note Support of external libraries (e.g.: OpenSSL) may be needed for + * some hashing algorithms. + */ +enum NTP_SYMM_KEY_HASHES +{ + NTP_SYMM_KEY_HASH_MD5, ///< NTP supports MD5 as key hashing algorithm + NTP_SYMM_KEY_HASH_SHA1, ///< NTP supports SHA1 as key hashing algorithm + N_NTP_SYMM_KEY_HASHES +}; + + + +/** + * @brief Flag masks associated with ::NTP_SYMM_KEY_HASHES + * + * @see ::NTP_SYMM_KEY_HASHES + */ +enum NTP_SYMM_KEY_HASH_MASKS +{ + NTP_SYMM_KEY_HASH_MSK_MD5 = ( 1UL << NTP_SYMM_KEY_HASH_MD5 ), ///< See ::NTP_SYMM_KEY_HASH_MD5 + NTP_SYMM_KEY_HASH_MSK_SHA1 = ( 1UL << NTP_SYMM_KEY_HASH_SHA1 ), ///< See ::NTP_SYMM_KEY_HASH_SHA1 +}; + + +/** + * @brief Name strings for defined NTP symm key hashes + * + * @see ::NTP_SYMM_KEY_HASHES + */ +#define NTP_SYMM_KEY_HASHES_STRS \ +{ \ + "MD5", \ + "SHA1" \ } + +/** + * @brief General NTP symmetric key limits to be read from a device + * + * ::NTP_SYMM_KEY_LIMITS::supp_hashes specifies supported hashing algorithms + * to create keys with. See ::NTP_SYMM_KEY_HASH_MASKS. Structure can be queried + * if ::NTP_MSK_SYMM_KEYS is set in ::NTP_GLB_INFO::supp_flags + */ +typedef struct +{ + uint16_t supp_hashes; ///< See ::NTP_SYMM_KEY_HASH_MASKS + uint16_t supp_flags; ///< See ::NTP_SYMM_KEY_FLAG_MASKS + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + uint32_t reserved_4; ///< Future use + +} NTP_SYMM_KEY_LIMITS; + +#define _mbg_swab_ntp_symm_key_limits( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->supp_hashes ); \ + _mbg_swab16( &(_p)->supp_flags ); \ +} while ( 0 ) + + + +/// Maximum length of a symmetric key. 128 byte was chosen to be +/// prepared for hash algorithms like SHA256, SH384, up to SHA512. +#define N_NTP_SYMM_KEY_LEN 128 + +/// Maximum number of whitelist entries which can be assigned to one key in +/// order to limit its usage +#define NTP_SYMM_KEY_WHITELIST_LEN 8 + + + +/** + * @brief NTP symmetric key specific settings + * + * This structure is used to configure a symmetric key for NTP. + */ +typedef struct +{ + uint16_t id; ///< Configurable key id (1..65534) + uint8_t hash; ///< See ::NTP_SYMM_KEY_HASHES + uint8_t reserved_1; ///< Future use + + uint16_t reserved_2; ///< Future use + uint8_t num_whitelist_entries; ///< Number of configured whitelist entries + ///< only valid if ::NTP_SYMM_KEY_WHITELIST_MSK is set in ::NTP_SYMM_KEY_LIMITS::supp_flags + uint8_t reserved_3; ///< Future use + + uint8_t key[N_NTP_SYMM_KEY_LEN]; ///< Hashed phrase, see ::N_NTP_SYMM_KEY_LEN + + MBG_IP_ADDR whitelist_entries[NTP_SYMM_KEY_WHITELIST_LEN]; ///< Whitelist of ip addresses see ::NTP_SYMM_KEY_WHITELIST_LEN + ///< may only be used if ::NTP_SYMM_KEY_WHITELIST_MSK is set in ::NTP_SYMM_KEY_LIMITS::supp_flags + +} NTP_SYMM_KEY_SETTINGS; + +#define _mbg_swab_ntp_symm_key_settings( _p ) \ +do \ +{ \ + unsigned i; \ + \ + _mbg_swab16( &(_p)->id ); \ + \ + for ( i = 0; i < NTP_SYMM_KEY_WHITELIST_LEN; ++i) \ + _mbg_swab_ip_addr( &(_p)->whitelist_entries[i] ); \ +} while ( 0 ) + + + +/** + * @brief NTP symmetric key settings, with index + * + * @see ::NTP_SYMM_KEY_SETTINGS + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + NTP_SYMM_KEY_SETTINGS settings; + +} NTP_SYMM_KEY_SETTINGS_IDX; + +#define _mbg_swab_ntp_symm_key_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_symm_key_settings( &(_p)->settings ); \ +} while ( 0 ) + + +/** + * @brief NTP symmkey info + * + * This structure is used to query a symmetric key for NTP. + */ +typedef struct +{ + NTP_SYMM_KEY_SETTINGS settings; + + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + uint32_t reserved_4; ///< Future use + +} NTP_SYMM_KEY_INFO; + +#define _mbg_swab_ntp_symm_key_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_symm_key_settings( &(_p)->settings ); \ +} while ( 0 ) + + +/** + * @brief NTP symm key info, with index + * + * @see ::NTP_SYMM_KEY_INFO + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + NTP_SYMM_KEY_INFO info; + +} NTP_SYMM_KEY_INFO_IDX; + +#define _mbg_swab_ntp_symm_key_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_symm_key_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief NTP trusted key settings + * + * This structure is used to configure a trusted symmetric key for NTP. + */ +typedef struct +{ + uint16_t id; ///< Configurable key id (1..65534) + uint16_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + +} NTP_TRUSTED_KEY_SETTINGS; + +#define _mbg_swab_ntp_trusted_key_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->id ); \ +} while ( 0 ) + + +/** + * @brief NTP trusted key settings, with index + * + * @see ::NTP_TRUSTED_KEY_SETTINGS + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + NTP_TRUSTED_KEY_SETTINGS settings; + +} NTP_TRUSTED_KEY_SETTINGS_IDX; + +#define _mbg_swab_ntp_trusted_key_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_trusted_key_settings( &(_p)->settings ); \ +} while ( 0 ) + +/** + * @brief NTP trusted key info + * + * This structure is used to query a trusted symmetric key for NTP. + */ +typedef struct +{ + NTP_TRUSTED_KEY_SETTINGS settings; + + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + uint32_t reserved_4; ///< Future use + +} NTP_TRUSTED_KEY_INFO; + +#define _mbg_swab_ntp_trusted_key_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_trusted_key_settings( &(_p)->settings ); \ +} while ( 0 ) + + +/** + * @brief NTP trusted key info, with index + * + * @see ::NTP_TRUSTED_KEY_INFO + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + NTP_TRUSTED_KEY_INFO info; + +} NTP_TRUSTED_KEY_INFO_IDX; + +#define _mbg_swab_ntp_trusted_key_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_trusted_key_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief Enumeration of NTP supported (various) misc options + * + * @see ::NTP_MISC_MSKS + */ +enum NTP_MISC_FLAGS +{ + NTP_MISC_FLAG_DRIFTFILE, ///< NTP supports driftfile + NTP_MISC_FLAG_ORPHAN_MODE, ///< NTP supports orphan mode + NTP_MISC_FLAG_LEAPFILE, ///< NTP supports leapfile + N_NTP_MISC_FLAGS +}; + + + +/** + * @brief Flag masks associated with ::NTP_MISC_FLAGS + * + * @see ::NTP_MISC_FLAGS + */ +enum NTP_MISC_MSKS +{ + NTP_MISC_MSK_DRIFTFILE = ( 1UL << NTP_MISC_FLAG_DRIFTFILE ), ///< See ::NTP_MISC_FLAG_DRIFTFILE + NTP_MISC_MSK_ORPHAN_MODE = ( 1UL << NTP_MISC_FLAG_ORPHAN_MODE ), ///< See ::NTP_MISC_FLAG_ORPHAN_MODE + NTP_MISC_MSK_LEAPFILE = ( 1UL << NTP_MISC_FLAG_LEAPFILE ) ///< See ::NTP_MISC_FLAG_LEAPFILE +}; + + + +/** + * @brief General NTP misc limits to be read from a device + * + * This structure can be used to determine various NTP options + * and can be queried if ::NTP_MSK_MISCELLANEOUS bit is set in ::NTP_GLB_INFO::supp_flags. + */ +typedef struct +{ + uint32_t supp_flags; ///< See ::NTP_MISC_MSKS + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + +} NTP_MISC_LIMITS; + +#define _mbg_swab_ntp_misc_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + + +/** + * @brief NTP driftfile settings to be read from / written to a device + * + * If ::NTP_MISC_MSK_DRIFTFILE is set in ::NTP_MISC_LIMITS::supp_flags + * ::NTP_MISC_DRIFTFILE_SETTINGS can be read / written. + */ +typedef struct +{ + uint8_t enable; ///< Enable / disable writing a driftfile + uint8_t reserved_1; ///< Future use + uint16_t reserved_2; ///< Future use + +} NTP_MISC_DRIFTFILE_SETTINGS; + +#define _mbg_swab_ntp_misc_driftfile_settings( _p ) \ +do \ +{ \ +} while ( 0 ) + + +/** + * @brief Enumeration of NTP supported (various) misc options + * + * @see ::NTP_ORPHAN_MODE_MSK + */ +enum NTP_ORPHAN_MODE_FLAGS +{ + NTP_ORPHAN_MODE_FLAG_SUPP_DISABLE, ///< Orphan Mode support disabling + + N_NTP_ORPHAN_MODE_FLAGS +}; + + + +/** + * @brief Flag masks associated with ::NTP_ORPHAN_MODE_FLAGS + * + * @see ::NTP_ORPHAN_MODE_FLAGS + */ +enum NTP_ORPHAN_MODE_MSK +{ + NTP_ORPHAN_MODE_MSK_SUPP_DISABLE = ( 1UL << NTP_ORPHAN_MODE_FLAG_SUPP_DISABLE ) ///< See ::NTP_ORPHAN_MODE_FLAG_SUPP_DISABLE +}; + + +/** + * @brief NTP orphan mode settings to be read from / written to a device + * + * If ::NTP_MISC_MSK_ORPHAN_MODE is set in ::NTP_MISC_LIMITS::supp_flags + * ::NTP_MISC_ORPHAN_MODE_SETTINGS can be read / written. + */ +typedef struct +{ + uint8_t enable; ///< Generally enable / disable orphan mode + uint8_t mode; ///< Stratum level when no ref source available + uint16_t wait_time; ///< Time until stratum is degraded (orphan mode active) in seconds + + uint32_t reserved_2; ///< Future use + +} NTP_MISC_ORPHAN_MODE_SETTINGS; + +#define _mbg_swab_ntp_misc_orphan_mode_settings( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->enable ); \ + _mbg_swab8( &(_p)->mode ); \ + _mbg_swab16( &(_p)->wait_time ); \ +} while ( 0 ) + + +/** + * @brief NTP orphan mode info + * + */ +typedef struct +{ + NTP_MISC_ORPHAN_MODE_SETTINGS settings; ///< See ::NTP_MISC_ORPHAN_MODE_SETTINGS + + uint32_t supp_flags; ///< See ::NTP_ORPHAN_MODE_MSK + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + +} NTP_MISC_ORPHAN_MODE_INFO; + +#define _mbg_swab_ntp_misc_orphan_mode_info( _p ) \ +do \ +{ \ + _mbg_swab_ntp_misc_orphan_mode_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +/** + * @brief NTP leapfile settings to be read from / written to a device + * + * If ::NTP_MISC_MSK_LEAPFILE is set in ::NTP_MISC_LIMITS::supp_flags + * ::NTP_MISC_LEAPFILE_SETTINGS can be read / written. + */ +typedef struct +{ + uint8_t enable; ///< Generally enable / disable leapfile + uint8_t reserved_1; ///< Stratum level when no ref source available + uint16_t reserved_2; ///< Future use + +} NTP_MISC_LEAPFILE_SETTINGS; + +#define _mbg_swab_ntp_misc_leapfile_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->reserved_2 ); \ +} while ( 0 ) + + /** * @brief Client settings of an NTP device * @@ -9314,19 +19140,24 @@ typedef struct */ typedef struct { - uint32_t reserved_1; ///< reserved, currently 0 - uint32_t reserved_2; ///< reserved, currently 0 + uint8_t num_peers; ///< number available peers + uint8_t reserved_1; ///< reserved, currently 0 + uint16_t reserved_2; ///< reserved, currently 0 + + uint32_t reserved_3; ///< reserved, currently 0 - uint32_t flags; ///< NTP flags, see ::NTP_FLAG_MASKS + uint32_t flags; ///< NTP flags, see @ref NTP_FLAG_MASKS } NTP_CLNT_MODE_SETTINGS; #define _mbg_swab_ntp_clnt_mode_settings( _p ) \ +do \ { \ _mbg_swab32( &(_p)->reserved_1 ); \ _mbg_swab32( &(_p)->reserved_2 ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) + /** @@ -9334,7 +19165,7 @@ typedef struct * * This structure can be used to determine possible NTP client settings and the current configuration */ -typedef struct +typedef struct ntp_clnt_mode_info_s { NTP_CLNT_MODE_SETTINGS settings; @@ -9346,19 +19177,80 @@ typedef struct uint32_t reserved_1; ///< reserved, currently 0 uint32_t reserved_2; ///< reserved, currently 0 - uint32_t supp_flags; ///< supported NTP flags, see ::NTP_FLAG_MASKS - uint32_t supp_peer_flags; ///< supported NTP flags for peers, see ::NTP_FLAG_MASKS + uint32_t supp_flags; ///< supported NTP flags, see @ref NTP_FLAG_MASKS + uint32_t supp_peer_flags; ///< supported NTP flags for peers, see @ref NTP_FLAG_MASKS } NTP_CLNT_MODE_INFO; #define _mbg_swab_ntp_clnt_mode_info( _p ) \ +do \ { \ _mbg_swab_ntp_clnt_mode_settings( &(_p)->settings ); \ _mbg_swab32( &(_p)->reserved_1 ); \ _mbg_swab32( &(_p)->reserved_2 ); \ _mbg_swab32( &(_p)->supp_flags ); \ _mbg_swab32( &(_p)->supp_peer_flags ); \ -} +} while ( 0 ) + + + +/** + * @brief General NTP peer settings limits to be read from a device + * + * Used to query from a device how many NTP associations are supported + * by the device, then index 0..::NTP_PEER_LIMITS::n_cur_peers-1 + * peer records can be read from a device. A maximum of + * ::NTP_PEER_LIMITS::n_supp_peers can be configured at all. + */ +typedef struct +{ + uint16_t n_supp_peers; ///< maximum number of configurable peers + uint16_t n_cur_peers; ///< current number of configured peers + + uint8_t poll_intv_min; ///< minimum supported NTP polling interval + uint8_t poll_intv_max; ///< maximum supported NTP polling interval + uint8_t reserved_1; ///< reserved, currently 0 + uint8_t reserved_2; ///< reserved, currently 0 + + uint32_t supp_assoc_types; ///< supported types of NTP associations + uint32_t reserved_3; ///< reserved, currently 0 + + uint32_t supp_flags_server; ///< supported flags for unicast associations + uint32_t supp_flags_peer; ///< supported flags for unicast symmetric-active assocations + uint32_t supp_flags_pool; ///< supported flags for unicast pool associations + uint32_t supp_flags_broadcast; ///< supported flags for broadcast associations + uint32_t supp_flags_multicast; ///< supported flags for multicast associations + uint32_t supp_flags_manycast; ///< supported flags for manycast associations + uint32_t supp_flags_broadcastclient; ///< supported flags for broadcast client associations + uint32_t supp_flags_multicastclient; ///< supported flags for multicast client associations + uint32_t supp_flags_manycastclient; ///< supported flags for manycast client associations + uint32_t reserved_4; ///< reserved, currently 0 + uint32_t reserved_5; ///< reserved, currently 0 + uint32_t reserved_6; ///< reserved, currently 0 + +} NTP_PEER_LIMITS; + +#define _mbg_swab_ntp_peer_limits( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->n_supp_peers ); \ + _mbg_swab16( &(_p)->n_cur_peers ); \ + _mbg_swab32( &(_p)->supp_assoc_types ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->supp_flags_server ); \ + _mbg_swab32( &(_p)->supp_flags_peer ); \ + _mbg_swab32( &(_p)->supp_flags_pool ); \ + _mbg_swab32( &(_p)->supp_flags_broadcast ); \ + _mbg_swab32( &(_p)->supp_flags_multicast ); \ + _mbg_swab32( &(_p)->supp_flags_manycast ); \ + _mbg_swab32( &(_p)->supp_flags_broadcastclient ); \ + _mbg_swab32( &(_p)->supp_flags_multicastclient ); \ + _mbg_swab32( &(_p)->supp_flags_manycastclient ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ + _mbg_swab32( &(_p)->reserved_6 ); \ +} while ( 0 ) + /** @@ -9373,90 +19265,103 @@ typedef struct */ typedef struct { - MBG_HOSTNAME hostname; ///< hostname or IP address of the peer + MBG_HOSTNAME hostname; ///< hostname or IP address of the peer, not used + ///< when the NTP_BROADCASTCLIENT flag is set uint8_t min_poll; ///< minimal configurable NTP polling interval uint8_t max_poll; ///< maximal configurable NTP polling interval uint8_t ttl; ///< time-to-live to use with broadcast/multicast/manycast uint8_t reserved_1; ///< reserved, currently 0 - uint32_t reserved_2; ///< reserved, currently 0 + uint32_t key; ///< ID of the symmetric key used with this association, + ///< this must be in the range 1-65534, 0 = disabled uint32_t reserved_3; ///< reserved, currently 0 uint32_t reserved_4; ///< reserved, currently 0 - uint32_t flags; ///< additional options configured, see ::NTP_FLAG_MASKS + uint32_t flags; ///< additional options configured, see @ref NTP_FLAG_MASKS } NTP_PEER_SETTINGS; #define _mbg_swab_ntp_peer_settings( _p ) \ +do \ { \ - _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->key ); \ _mbg_swab32( &(_p)->reserved_3 ); \ _mbg_swab32( &(_p)->reserved_4 ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) + + /** * @brief Peer settings for NTP devices * * @see ::NTP_PEER_SETTINGS */ -typedef struct +typedef struct ntp_peer_settings_idx_s { - uint32_t idx; + MBG_MSG_IDX_32 idx; NTP_PEER_SETTINGS peer_settings; } NTP_PEER_SETTINGS_IDX; #define _mbg_swab_ntp_peer_settings_idx( _p ) \ +do \ { \ _mbg_swab32( &(_p)->idx ); \ _mbg_swab_ntp_peer_settings( &(_p)->peer_settings ); \ -} +} while ( 0 ) + -#ifdef DEBUG /** - * @brief Dummy structure for later NTP server implementations, not used, yet + * @brief Server settings of an NTP device + * + * This structure should be sent to an NTP server to configure server parameters */ typedef struct { - uint32_t reserved_1; ///< reserved, currently 0 - uint32_t reserved_2; ///< reserved, currently 0 + uint8_t num_refclks; ///< number of available refclks @ref NTP_REFCLK_CFG_INFO + uint8_t reserved_1; ///< reserved, currently 0 + uint16_t reserved_2; ///< reserved, currently 0 - uint32_t flags; ///< NTP flags, see ::NTP_FLAG_MASKS + uint32_t reserved_3; ///< reserved, currently 0 + + uint32_t flags; ///< NTP flags, see @ref NTP_FLAG_MASKS } NTP_SRV_MODE_SETTINGS; #define _mbg_swab_ntp_srv_mode_settings( _p ) \ +do \ { \ - _mbg_swab32( &(_p)->reserved_1 ); \ - _mbg_swab32( &(_p)->reserved_2 ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) /** - * @brief Dummy structure for later NTP server implementations + * @brief Server settings info of an NTP device + * + * This structure should be used to query an NTP server configuration from a device */ -typedef struct +typedef struct ntp_srv_mode_info_s { NTP_SRV_MODE_SETTINGS settings; - uint32_t reserved_1; ///< reserved, currently 0 - uint32_t reserved_2; ///< reserved, currently 0 + uint8_t max_refclks; ///< number of supported refclks @ref NTP_REFCLK_CFG_INFO + uint8_t reserved_1; ///< reserved, currently 0 + uint16_t reserved_2; ///< reserved, currently 0 + + uint32_t reserved_3; ///< reserved, currently 0 - uint32_t supp_flags; ///< supported NTP flags, see ::NTP_FLAG_MASKS + uint32_t supp_flags; ///< supported NTP flags, see @ref NTP_FLAG_MASKS } NTP_SRV_MODE_INFO; #define _mbg_swab_ntp_srv_mode_info( _p ) \ +do \ { \ _mbg_swab_ntp_srv_mode_settings( &(_p)->settings ); \ - _mbg_swab32( &(_p)->reserved_1 ); \ - _mbg_swab32( &(_p)->reserved_2 ); \ _mbg_swab32( &(_p)->supp_flags ); \ -} -#endif // DEBUG +} while ( 0 ) /** @@ -9473,30 +19378,31 @@ typedef struct } NTP_SHORT_TSTAMP; #define _mbg_swab_ntp_short_tstamp( _p ) \ +do \ { \ _mbg_swab16( &(_p)->seconds ); \ _mbg_swab16( &(_p)->fractions ); \ } + /** * @brief Structure that represents a timestamp in NTP Timestamp Format - * - * Maximal value for seconds is 4294967296. - * Minimal resolution of fractions is 233 picoseconds. */ typedef struct { - uint32_t seconds; - uint32_t fractions; + uint32_t seconds; ///< seconds since NTP epoch, see ::NTP_SEC_BIAS + uint32_t fractions; ///< binary fractional part of a second, 0xFFFFFFFF -> 0.9999999... s (resolution 2^-32s =~ 233 ps) } NTP_TSTAMP; #define _mbg_swab_ntp_tstamp( _p ) \ +do \ { \ _mbg_swab32( &(_p)->seconds ); \ _mbg_swab32( &(_p)->fractions ); \ -} +} while ( 0 ) + /** @@ -9520,6 +19426,7 @@ enum NTP_IMPL * for multi-language strings can be found in tmonlstr.h. */ #define MBG_NTP_IMPL_STR_ENG "Implemetation Type:" + #define MBG_NTP_IMPL_STR_ENG_UNKNOWN "Unknown NTP implementation" #define MBG_NTP_IMPL_STR_ENG_NTPD "Network Time Protocol daemon (ntpd)" #define MBG_NTP_IMPL_STR_ENG_NTPDATE "NTP client only (ntpdate)" @@ -9539,6 +19446,7 @@ enum NTP_IMPL } + /** * @brief Enumeration of CPU types using NTP * @@ -9561,6 +19469,7 @@ enum NTP_CPU_TYPES }; + /** * @brief Name strings for known CPU types using NTP * @@ -9582,6 +19491,7 @@ enum NTP_CPU_TYPES } + /** * @brief Enumeration of operating systems using NTP * @@ -9599,6 +19509,7 @@ enum NTP_SYSTEMS }; + /** * @brief Name strings for operating systens using NTP * @@ -9615,6 +19526,7 @@ enum NTP_SYSTEMS } + /** * @brief Enumeration of NTP leap indication bits * @@ -9630,11 +19542,14 @@ enum NTP_LI_BITS N_NTP_LI_BITS }; + + /* * Default initializers for English leapsecond string names. Initializers * for multi-language strings can be found in tmonlstr.h. */ #define MBG_NTP_LEAP_STR_ENG "Leapsecond indication:" + #define MBG_NTP_LEAP_STR_ENG_NONE "None" #define MBG_NTP_LEAP_STR_ENG_ADD_SEC "Insert second" #define MBG_NTP_LEAP_STR_ENG_DEL_SEC "Delete second" @@ -9649,6 +19564,7 @@ enum NTP_LI_BITS } + /** * @brief Enumeration of NTP synchronization source bits * @@ -9670,11 +19586,14 @@ enum NTP_SYNC_SRC_BITS N_NTP_SYNC_SRC_BITS }; + + /* * Default initializers for English sync source string names. Initializers * for multi-language strings can be found in tmonlstr.h. */ #define MBG_NTP_SYNC_SRC_STR_ENG_LABEL "Sync Source:" + #define MBG_NTP_SYNC_SRC_STR_ENG_UNSPEC "Not yet synchronized" #define MBG_NTP_SYNC_SRC_STR_ENG_PPS "Pulse per second signal" #define MBG_NTP_SYNC_SRC_STR_ENG_LF_RADIO "VLF/LF radio" @@ -9701,6 +19620,7 @@ enum NTP_SYNC_SRC_BITS } + /** * @brief Enumeration of NTP system event message bits * @@ -9728,12 +19648,15 @@ enum NTP_SYS_EVT_BITS N_NTP_SYS_EVT_BITS }; + + /* * Default initializers for English sync source string names. Initializers * for multi-language strings can be found in tmonlstr.h. */ #define MBG_NTP_SYS_EVT_STR_ENG_CNT_LABEL "System Event Counter:" #define MBG_NTP_SYS_EVT_STR_ENG_MSG_LABEL "System Event Message:" + #define MBG_NTP_SYS_EVT_STR_ENG_UNSPEC "Unspecified NTP event" #define MBG_NTP_SYS_EVT_STR_ENG_FREQ_NOT_SET "Frequency file not available" #define MBG_NTP_SYS_EVT_STR_ENG_FREQ_SET "Frequency set from frequency file" @@ -9772,6 +19695,8 @@ enum NTP_SYS_EVT_BITS MBG_NTP_SYS_EVT_STR_ENG_STALE_LS_VALUES \ } + + /** * @brief Enumeration of supported NTP system state values * @@ -9779,19 +19704,22 @@ enum NTP_SYS_EVT_BITS */ enum NTP_SYS_STATE_SUPP_FLAGS { - NTP_SYS_STATE_SUPP_STD = 0, ///< supports standard values of ::NTP_SYS_STATE, all fields except below and reserved - NTP_SYS_STATE_SUPP_EVENTS, ///< supports sys state events (::NTP_SYS_STATE::sys_evt_cnt, ::NTP_SYS_STATE::sys_rec_evt) - NTP_SYS_STATE_SUPP_PRECISION, ///< supports precision indication, see ::NTP_SYS_STATE::precision - NTP_SYS_STATE_SUPP_ROOT_DELAY, ///< supports root delay to syspeer, see ::NTP_SYS_STATE::root_delay - NTP_SYS_STATE_SUPP_ROOT_DISP, ///< supports root dispersion, see ::NTP_SYS_STATE::root_disp - NTP_SYS_STATE_SUPP_FREQ, ///< supports frequency offset, see ::NTP_SYS_STATE::freq - NTP_SYS_STATE_SUPP_SYS_JITTER, ///< supports combined jitter, see ::NTP_SYS_STATE::sys_jitter - NTP_SYS_STATE_SUPP_CLK_JITTER, ///< supports clock jitter, see ::NTP_SYS_STATE::clk_jitter - NTP_SYS_STATE_SUPP_CLK_WANDER, ///< supports clock wander, see ::NTP_SYS_STATE::clk_wander + NTP_SYS_STATE_SUPP_STD = 0, ///< supports standard values of ::NTP_SYS_STATE, all fields except below and reserved + NTP_SYS_STATE_SUPP_EVENTS, ///< supports sys state events (::NTP_SYS_STATE::sys_evt_cnt, ::NTP_SYS_STATE::sys_rec_evt) + NTP_SYS_STATE_SUPP_PRECISION, ///< supports precision indication, see ::NTP_SYS_STATE::precision + NTP_SYS_STATE_SUPP_ROOT_DELAY, ///< supports root delay to syspeer, see ::NTP_SYS_STATE::root_delay + NTP_SYS_STATE_SUPP_ROOT_DISP, ///< supports root dispersion, see ::NTP_SYS_STATE::root_disp + NTP_SYS_STATE_SUPP_FREQ, ///< supports frequency offset, see ::NTP_SYS_STATE::freq + NTP_SYS_STATE_SUPP_SYS_JITTER, ///< supports combined jitter, see ::NTP_SYS_STATE::sys_jitter + NTP_SYS_STATE_SUPP_CLK_JITTER, ///< supports clock jitter, see ::NTP_SYS_STATE::clk_jitter + NTP_SYS_STATE_SUPP_CLK_WANDER, ///< supports clock wander, see ::NTP_SYS_STATE::clk_wander + NTP_SYS_STATE_SUPP_SYS_ASSOC, ///< supports sys assoc ID as sys peer, see ::NTP_SYS_STATE::sys_assoc + NTP_SYS_STATE_SUPP_SERVICE_STATE, ///< supports service state, see ::NTP_SYS_STATE::service_state N_NTP_SYS_STATE_SUPP_FLAGS }; + /** * @brief Flag masks for NTP_SYS_STATE_SUPP_FLAGS * @@ -9801,24 +19729,55 @@ enum NTP_SYS_STATE_SUPP_FLAGS */ enum NTP_SYS_STATE_SUPP_FLAG_MASKS { - NTP_SYS_STATE_SUPP_STD_MSK = ( 1UL << NTP_SYS_STATE_SUPP_STD ), ///< see ::NTP_SYS_STATE_SUPP_STD - NTP_SYS_STATE_SUPP_EVENTS_MSK = ( 1UL << NTP_SYS_STATE_SUPP_EVENTS ), ///< see ::NTP_SYS_STATE_SUPP_EVENTS - NTP_SYS_STATE_SUPP_PRECISION_MSK = ( 1UL << NTP_SYS_STATE_SUPP_PRECISION ), ///< see ::NTP_SYS_STATE_SUPP_PRECISION - NTP_SYS_STATE_SUPP_ROOT_DELAY_MSK = ( 1UL << NTP_SYS_STATE_SUPP_ROOT_DELAY ), ///< see ::NTP_SYS_STATE_SUPP_ROOT_DELAY - NTP_SYS_STATE_SUPP_ROOT_DISP_MSK = ( 1UL << NTP_SYS_STATE_SUPP_ROOT_DISP ), ///< see ::NTP_SYS_STATE_SUPP_ROOT_DISP - NTP_SYS_STATE_SUPP_FREQ_MSK = ( 1UL << NTP_SYS_STATE_SUPP_FREQ ), ///< see ::NTP_SYS_STATE_SUPP_FREQ - NTP_SYS_STATE_SUPP_SYS_JITTER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SYS_JITTER ), ///< see ::NTP_SYS_STATE_SUPP_SYS_JITTER - NTP_SYS_STATE_SUPP_CLK_JITTER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_JITTER ), ///< see ::NTP_SYS_STATE_SUPP_CLK_JITTER - NTP_SYS_STATE_SUPP_CLK_WANDER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_WANDER ) ///< see ::NTP_SYS_STATE_SUPP_CLK_WANDER + NTP_SYS_STATE_SUPP_STD_MSK = ( 1UL << NTP_SYS_STATE_SUPP_STD ), ///< See ::NTP_SYS_STATE_SUPP_STD + NTP_SYS_STATE_SUPP_EVENTS_MSK = ( 1UL << NTP_SYS_STATE_SUPP_EVENTS ), ///< See ::NTP_SYS_STATE_SUPP_EVENTS + NTP_SYS_STATE_SUPP_PRECISION_MSK = ( 1UL << NTP_SYS_STATE_SUPP_PRECISION ), ///< See ::NTP_SYS_STATE_SUPP_PRECISION + NTP_SYS_STATE_SUPP_ROOT_DELAY_MSK = ( 1UL << NTP_SYS_STATE_SUPP_ROOT_DELAY ), ///< See ::NTP_SYS_STATE_SUPP_ROOT_DELAY + NTP_SYS_STATE_SUPP_ROOT_DISP_MSK = ( 1UL << NTP_SYS_STATE_SUPP_ROOT_DISP ), ///< See ::NTP_SYS_STATE_SUPP_ROOT_DISP + NTP_SYS_STATE_SUPP_FREQ_MSK = ( 1UL << NTP_SYS_STATE_SUPP_FREQ ), ///< See ::NTP_SYS_STATE_SUPP_FREQ + NTP_SYS_STATE_SUPP_SYS_JITTER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SYS_JITTER ), ///< See ::NTP_SYS_STATE_SUPP_SYS_JITTER + NTP_SYS_STATE_SUPP_CLK_JITTER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_JITTER ), ///< See ::NTP_SYS_STATE_SUPP_CLK_JITTER + NTP_SYS_STATE_SUPP_CLK_WANDER_MSK = ( 1UL << NTP_SYS_STATE_SUPP_CLK_WANDER ), ///< See ::NTP_SYS_STATE_SUPP_CLK_WANDER + NTP_SYS_STATE_SUPP_SYS_ASSOC_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SYS_ASSOC ), ///< See ::NTP_SYS_STATE_SUPP_SYS_ASSOC + NTP_SYS_STATE_SUPP_SERVICE_STATE_MSK = ( 1UL << NTP_SYS_STATE_SUPP_SERVICE_STATE ) ///< See ::NTP_SYS_STATE_SUPP_SERVICE_STATE +}; + + +/** + * @brief Enumeration of supported NTP service state values + */ +enum MBG_NTP_SERVICE_STATES +{ + MBG_NTP_SERVICE_INIT, + MBG_NTP_SERVICE_SYNC, + MBG_NTP_SERVICE_ASYNC, + MBG_NTP_SERVICE_STOPPED, + N_MBG_NTP_SERVICE_STATES }; +/* + * Default initializers for NTP service state string names. + */ + +#define MBG_NTP_SERVICE_INIT_STR "NTP service initializing" +#define MBG_NTP_SERVICE_SYNC_STR "NTP service synchronized" +#define MBG_NTP_SERVICE_ASYNC_STR "NTP service not synchronized" +#define MBG_NTP_SERVICE_STOPPED_STR "NTP service stopped" + +#define MBG_NTP_SERVICE_STATES_STRS \ +{ \ + MBG_NTP_SERVICE_INIT_STR, \ + MBG_NTP_SERVICE_SYNC_STR, \ + MBG_NTP_SERVICE_ASYNC_STR, \ + MBG_NTP_SERVICE_STOPPED_STR \ +} /** * @brief Structure that represents the current system status of an NTP device * * This structure can be requested from a monitoring program to determine the device system status */ -typedef struct +typedef struct ntp_sys_state_s { uint32_t supp_flags; ///< Supported NTP system state values, see ::NTP_SYS_STATE_SUPP_FLAG_MASKS @@ -9838,17 +19797,17 @@ typedef struct uint8_t stratum; ///< Current stratum level of the system int8_t precision; ///< Precision of the system clock (2^precision) - uint16_t reserved_1; ///< Reserved, currently always 0 + uint16_t sys_assoc; ///< Association ID of the current system peer, do not use NTP_SYS_STATE::sys_peer if this is supported int32_t root_delay; ///< [us] Total roundtrip delay to the system peer int32_t root_disp; ///< [us] Total dispersion to the system peer - MBG_IP_ADDR ref_id; ///< Reference ID of the current system peer, see ::MBG_IP_ADDR + MBG_IP_ADDR ref_id; ///< Reference ID of the current system peer, see ::MBG_IP_ADDR NTP_TSTAMP ref_time; ///< Last time the system time has been adjusted, see ::NTP_TSTAMP NTP_TSTAMP sys_time; ///< Current system time, see ::NTP_TSTAMP - uint16_t sys_peer; ///< Assocation ID of the current system peer + uint16_t sys_peer; ///< Index of the current system peer uint8_t poll; ///< Current polling interval for the system peer (tc) uint8_t minpoll; ///< Minimal polling interval for the system peer (mintc) @@ -9859,11 +19818,62 @@ typedef struct int32_t clk_jitter; ///< [us] Jitter of the clock int32_t clk_wander; ///< [ppb] Frequency wander of the clock - uint32_t reserved_2; ///< Reserved, currently always 0 + uint8_t service_state; ///< Current state of the NTP service see ::MBG_NTP_SERVICE_STATES + uint8_t reserved_1; ///< Reserved, currently always 0 + uint16_t reserved_2; ///< Reserved, currently always 0 + uint32_t reserved_3; ///< Reserved, currently always 0 } NTP_SYS_STATE; +#define _mbg_swab_ntp_sys_state( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_flags ); \ + \ + _mbg_swab8( &(_p)->leap_ind ); \ + _mbg_swab8( &(_p)->sys_sync_src ); \ + _mbg_swab8( &(_p)->sys_evt_cnt ); \ + _mbg_swab8( &(_p)->sys_rec_evt ); \ + \ + _mbg_swab8( &(_p)->impl_type ); \ + _mbg_swab8( &(_p)->major_version ); \ + _mbg_swab8( &(_p)->minor_version ); \ + _mbg_swab8( &(_p)->micro_version ); \ + \ + _mbg_swab16( &(_p)->patch_lvl ); \ + _mbg_swab8( &(_p)->cpu_type ); \ + _mbg_swab8( &(_p)->system ); \ + \ + _mbg_swab8( &(_p)->stratum ); \ + _mbg_swab8( &(_p)->precision ); \ + _mbg_swab16( &(_p)->sys_assoc ); \ + \ + _mbg_swab32( &(_p)->root_delay ); \ + _mbg_swab32( &(_p)->root_disp ); \ + \ + _mbg_swab_ip_addr( &(_p)->ref_id ); \ + \ + _mbg_swab_ntp_tstamp( &(_p)->ref_time ); \ + _mbg_swab_ntp_tstamp( &(_p)->sys_time ); \ + \ + _mbg_swab16( &(_p)->sys_peer ); \ + _mbg_swab8( &(_p)->poll ); \ + _mbg_swab8( &(_p)->minpoll ); \ + \ + _mbg_swab64( &(_p)->offset ); \ + \ + _mbg_swab32( &(_p)->freq ); \ + _mbg_swab32( &(_p)->sys_jitter ); \ + _mbg_swab32( &(_p)->clk_jitter ); \ + _mbg_swab32( &(_p)->clk_wander ); \ + \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + \ +} while ( 0 ) + + /** * @brief Enumeration of NTP mode bits @@ -9884,6 +19894,8 @@ enum NTP_MODE_BITS N_NTP_MODE_BITS }; + + /* * Default initializers for English NTP peer mode string names. Initializers * for multi-language strings can be found in tmonlstr.h. @@ -9913,6 +19925,7 @@ enum NTP_MODE_BITS } + /** * @brief Enumeration of NTP peer reach status * @@ -9931,6 +19944,8 @@ enum NTP_REACH_STAT_BITS N_NTP_REACH_STAT_BITS }; + + /* * Default initializers for English reach status string names. Initializers * for multi-language strings can be found in tmonlstr.h. @@ -9959,6 +19974,7 @@ enum NTP_REACH_STAT_BITS } + /** * @brief Enumeration of NTP peer selection status * @@ -9978,6 +19994,8 @@ enum NTP_PEER_SEL_STATUS_BITS N_NTP_PEER_SEL_STATUS_BITS }; + + /* * Default initializers for English peer select status string names. Initializers * for multi-language strings can be found in tmonlstr.h. @@ -10006,6 +20024,7 @@ enum NTP_PEER_SEL_STATUS_BITS } + /** * @brief Enumeration of NTP peer status codes * @@ -10032,11 +20051,11 @@ enum NTP_PEER_STATUS_FLAGS */ enum NTP_PEER_STATUS_FLAG_MASKS { - NTP_PEER_STATUS_BCST_MSK = ( 1UL << NTP_PEER_STATUS_BCST ), ///< see ::NTP_PEER_STATUS_BCST - NTP_PEER_STATUS_REACH_MSK = ( 1UL << NTP_PEER_STATUS_REACH ), ///< see ::NTP_PEER_STATUS_REACH - NTP_PEER_STATUS_AUTHENB_MSK = ( 1UL << NTP_PEER_STATUS_AUTHENB ), ///< see ::NTP_PEER_STATUS_AUTHENB - NTP_PEER_STATUS_AUTH_MSK = ( 1UL << NTP_PEER_STATUS_AUTH ), ///< see ::NTP_PEER_STATUS_AUTH - NTP_PEER_STATUS_CONFIG_MSK = ( 1UL << NTP_PEER_STATUS_CONFIG ), ///< see ::NTP_PEER_STATUS_CONFIG + NTP_PEER_STATUS_BCST_MSK = ( 1UL << NTP_PEER_STATUS_BCST ), ///< See ::NTP_PEER_STATUS_BCST + NTP_PEER_STATUS_REACH_MSK = ( 1UL << NTP_PEER_STATUS_REACH ), ///< See ::NTP_PEER_STATUS_REACH + NTP_PEER_STATUS_AUTHENB_MSK = ( 1UL << NTP_PEER_STATUS_AUTHENB ), ///< See ::NTP_PEER_STATUS_AUTHENB + NTP_PEER_STATUS_AUTH_MSK = ( 1UL << NTP_PEER_STATUS_AUTH ), ///< See ::NTP_PEER_STATUS_AUTH + NTP_PEER_STATUS_CONFIG_MSK = ( 1UL << NTP_PEER_STATUS_CONFIG ), ///< See ::NTP_PEER_STATUS_CONFIG }; @@ -10045,6 +20064,7 @@ enum NTP_PEER_STATUS_FLAG_MASKS * for multi-language strings can be found in tmonlstr.h. */ #define MBG_NTP_PEER_STATUS_STR_ENG_LABEL "Peer Status:" + #define MBG_NTP_PEER_STATUS_STR_ENG_BCST "Broadcast association" #define MBG_NTP_PEER_STATUS_STR_ENG_REACH "Host reachable" #define MBG_NTP_PEER_STATUS_STR_ENG_AUTHENB "Authentication enabled" @@ -10060,6 +20080,7 @@ enum NTP_PEER_STATUS_FLAG_MASKS } + /** * @brief Enumeration of NTP peer event message codes * @@ -10087,12 +20108,15 @@ enum NTP_PEER_EVT_BITS N_NTP_PEER_EVT_BITS }; + + /* * Default initializers for English event message codes. Initializers * for multi-language strings can be found in tmonlstr.h. */ #define MBG_NTP_PEER_EVT_STR_ENG_CNT_LABEL "Peer Event Counter:" #define MBG_NTP_PEER_EVT_STR_ENG_MSG_LABEL "Peer Event Message:" + #define MBG_NTP_PEER_EVT_STR_ENG_UNSPEC "Unspecified NTP event" #define MBG_NTP_PEER_EVT_STR_ENG_MOBILIZE "Association mobilized" #define MBG_NTP_PEER_EVT_STR_ENG_DEMOBILIZE "Association demobilized" @@ -10157,6 +20181,7 @@ enum NTP_FLASH_STAT_FLAGS }; + /** * @brief Flag masks for ::NTP_FLASH_STAT_FLAGS * @@ -10166,27 +20191,29 @@ enum NTP_FLASH_STAT_FLAGS */ enum NTP_FLASH_STAT_FLAG_MASKS { - NTP_FLASH_STAT_PKT_DUP_MSK = ( 1UL << NTP_FLASH_STAT_PKT_DUP ), ///< see ::NTP_FLASH_STAT_PKT_DUP - NTP_FLASH_STAT_PKT_BOGUS_MSK = ( 1UL << NTP_FLASH_STAT_PKT_BOGUS ), ///< see ::NTP_FLASH_STAT_PKT_BOGUS - NTP_FLASH_STAT_PKT_UNSYNC_MSK = ( 1UL << NTP_FLASH_STAT_PKT_UNSYNC ), ///< see ::NTP_FLASH_STAT_PKT_UNSYNC - NTP_FLASH_STAT_PKT_DENIED_MSK = ( 1UL << NTP_FLASH_STAT_PKT_DENIED ), ///< see ::NTP_FLASH_STAT_PKT_DENIED - NTP_FLASH_STAT_PKT_AUTH_MSK = ( 1UL << NTP_FLASH_STAT_PKT_AUTH ), ///< see ::NTP_FLASH_STAT_PKT_AUTH - NTP_FLASH_STAT_PKT_STRATUM_MSK = ( 1UL << NTP_FLASH_STAT_PKT_STRATUM ), ///< see ::NTP_FLASH_STAT_PKT_STRATUM - NTP_FLASH_STAT_PKT_HEADER_MSK = ( 1UL << NTP_FLASH_STAT_PKT_HEADER ), ///< see ::NTP_FLASH_STAT_PKT_HEADER - NTP_FLASH_STAT_PKT_AUTOKEY_MSK = ( 1UL << NTP_FLASH_STAT_PKT_AUTOKEY ), ///< see ::NTP_FLASH_STAT_PKT_AUTOKEY - NTP_FLASH_STAT_PKT_CRYPTO_MSK = ( 1UL << NTP_FLASH_STAT_PKT_CRYPTO ), ///< see ::NTP_FLASH_STAT_PKT_CRYPTO - NTP_FLASH_STAT_PEER_STRATUM_MSK = ( 1UL << NTP_FLASH_STAT_PEER_STRATUM ), ///< see ::NTP_FLASH_STAT_PEER_STRATUM - NTP_FLASH_STAT_PEER_DIST_MSK = ( 1UL << NTP_FLASH_STAT_PEER_DIST ), ///< see ::NTP_FLASH_STAT_PEER_DIST - NTP_FLASH_STAT_PEER_LOOP_MSK = ( 1UL << NTP_FLASH_STAT_PEER_LOOP ), ///< see ::NTP_FLASH_STAT_PEER_LOOP - NTP_FLASH_STAT_PEER_UNREACH_MSK = ( 1UL << NTP_FLASH_STAT_PEER_UNREACH ), ///< see ::NTP_FLASH_STAT_PEER_UNREACH + NTP_FLASH_STAT_PKT_DUP_MSK = ( 1UL << NTP_FLASH_STAT_PKT_DUP ), ///< See ::NTP_FLASH_STAT_PKT_DUP + NTP_FLASH_STAT_PKT_BOGUS_MSK = ( 1UL << NTP_FLASH_STAT_PKT_BOGUS ), ///< See ::NTP_FLASH_STAT_PKT_BOGUS + NTP_FLASH_STAT_PKT_UNSYNC_MSK = ( 1UL << NTP_FLASH_STAT_PKT_UNSYNC ), ///< See ::NTP_FLASH_STAT_PKT_UNSYNC + NTP_FLASH_STAT_PKT_DENIED_MSK = ( 1UL << NTP_FLASH_STAT_PKT_DENIED ), ///< See ::NTP_FLASH_STAT_PKT_DENIED + NTP_FLASH_STAT_PKT_AUTH_MSK = ( 1UL << NTP_FLASH_STAT_PKT_AUTH ), ///< See ::NTP_FLASH_STAT_PKT_AUTH + NTP_FLASH_STAT_PKT_STRATUM_MSK = ( 1UL << NTP_FLASH_STAT_PKT_STRATUM ), ///< See ::NTP_FLASH_STAT_PKT_STRATUM + NTP_FLASH_STAT_PKT_HEADER_MSK = ( 1UL << NTP_FLASH_STAT_PKT_HEADER ), ///< See ::NTP_FLASH_STAT_PKT_HEADER + NTP_FLASH_STAT_PKT_AUTOKEY_MSK = ( 1UL << NTP_FLASH_STAT_PKT_AUTOKEY ), ///< See ::NTP_FLASH_STAT_PKT_AUTOKEY + NTP_FLASH_STAT_PKT_CRYPTO_MSK = ( 1UL << NTP_FLASH_STAT_PKT_CRYPTO ), ///< See ::NTP_FLASH_STAT_PKT_CRYPTO + NTP_FLASH_STAT_PEER_STRATUM_MSK = ( 1UL << NTP_FLASH_STAT_PEER_STRATUM ), ///< See ::NTP_FLASH_STAT_PEER_STRATUM + NTP_FLASH_STAT_PEER_DIST_MSK = ( 1UL << NTP_FLASH_STAT_PEER_DIST ), ///< See ::NTP_FLASH_STAT_PEER_DIST + NTP_FLASH_STAT_PEER_LOOP_MSK = ( 1UL << NTP_FLASH_STAT_PEER_LOOP ), ///< See ::NTP_FLASH_STAT_PEER_LOOP + NTP_FLASH_STAT_PEER_UNREACH_MSK = ( 1UL << NTP_FLASH_STAT_PEER_UNREACH ), ///< See ::NTP_FLASH_STAT_PEER_UNREACH }; + + /* * Default initializers for English ntp flash state mask. Initializers * for multi-language strings can be found in tmonlstr.h. */ - #define MBG_NTP_FLASH_STR_ENG_LABEL "Flash Status:" + #define MBG_NTP_FLASH_STR_ENG_PKT_DUP "Duplicate packet" #define MBG_NTP_FLASH_STR_ENG_PKT_BOGUS "Bogus packet" #define MBG_NTP_FLASH_STR_ENG_PKT_UNSYNC "Server not synchronized" @@ -10220,6 +20247,7 @@ enum NTP_FLASH_STAT_FLAG_MASKS } + /** * @brief Enumeration of supported NTP peer state values * @@ -10227,7 +20255,7 @@ enum NTP_FLASH_STAT_FLAG_MASKS */ enum NTP_PEER_STATE_SUPP_FLAGS { - NTP_PEER_STATE_SUPP_STD = 0, ///< supports standard values of ::NTP_PEER_STATE, all fields except below and reserved + NTP_PEER_STATE_SUPP_STD, ///< supports standard values of ::NTP_PEER_STATE, all fields except below and reserved NTP_PEER_STATE_SUPP_ASS_ID, ///< supports association ID, see ::NTP_PEER_STATE::ass_id NTP_PEER_STATE_SUPP_EVENTS, ///< supports peer state events (NTP_PEER_STATE::peer_evt_cnt, NTP_PEER_STATE::peer_rec_evt) NTP_PEER_STATE_SUPP_REACH_STAT, ///< supports peer reach status, see ::NTP_PEER_STATE::peer_reach_stat @@ -10253,22 +20281,23 @@ enum NTP_PEER_STATE_SUPP_FLAGS */ enum NTP_PEER_STATE_SUPP_FLAG_MASKS { - NTP_PEER_STATE_SUPP_STD_MSK = ( 1UL << NTP_PEER_STATE_SUPP_STD ), ///< see ::NTP_PEER_STATE_SUPP_STD - NTP_PEER_STATE_SUPP_ASS_ID_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ASS_ID ), ///< see ::NTP_PEER_STATE_SUPP_ASS_ID - NTP_PEER_STATE_SUPP_EVENTS_MSK = ( 1UL << NTP_PEER_STATE_SUPP_EVENTS ), ///< see ::NTP_PEER_STATE_SUPP_EVENTS - NTP_PEER_STATE_SUPP_REACH_STAT_MSK = ( 1UL << NTP_PEER_STATE_SUPP_REACH_STAT ), ///< see ::NTP_PEER_STATE_SUPP_REACH_STAT - NTP_PEER_STATE_SUPP_PRECISION_MSK = ( 1UL << NTP_PEER_STATE_SUPP_PRECISION ), ///< see ::NTP_PEER_STATE_SUPP_PRECISION - NTP_PEER_STATE_SUPP_ROOT_DELAY_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ROOT_DELAY ), ///< see ::NTP_PEER_STATE_SUPP_ROOT_DELAY - NTP_PEER_STATE_SUPP_ROOT_DISP_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ROOT_DISP ), ///< see ::NTP_PEER_STATE_SUPP_ROOT_DISP - NTP_PEER_STATE_SUPP_HEADWAY_MSK = ( 1UL << NTP_PEER_STATE_SUPP_HEADWAY ), ///< see ::NTP_PEER_STATE_SUPP_HEADWAY - NTP_PEER_STATE_SUPP_FLASH_STAT_MSK = ( 1UL << NTP_PEER_STATE_SUPP_FLASH_STAT ), ///< see ::NTP_PEER_STATE_SUPP_FLASH_STAT - NTP_PEER_STATE_SUPP_KEY_ID_MSK = ( 1UL << NTP_PEER_STATE_SUPP_KEY_ID ), ///< see ::NTP_PEER_STATE_SUPP_KEY_ID - NTP_PEER_STATE_SUPP_DISP_MSK = ( 1UL << NTP_PEER_STATE_SUPP_DISP ), ///< see ::NTP_PEER_STATE_SUPP_DISP - NTP_PEER_STATE_SUPP_JITTER_MSK = ( 1UL << NTP_PEER_STATE_SUPP_JITTER ), ///< see ::NTP_PEER_STATE_SUPP_JITTER - NTP_PEER_STATE_SUPP_XLEAVE_MSK = ( 1UL << NTP_PEER_STATE_SUPP_XLEAVE ), ///< see ::NTP_PEER_STATE_SUPP_XLEAVE + NTP_PEER_STATE_SUPP_STD_MSK = ( 1UL << NTP_PEER_STATE_SUPP_STD ), ///< See ::NTP_PEER_STATE_SUPP_STD + NTP_PEER_STATE_SUPP_ASS_ID_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ASS_ID ), ///< See ::NTP_PEER_STATE_SUPP_ASS_ID + NTP_PEER_STATE_SUPP_EVENTS_MSK = ( 1UL << NTP_PEER_STATE_SUPP_EVENTS ), ///< See ::NTP_PEER_STATE_SUPP_EVENTS + NTP_PEER_STATE_SUPP_REACH_STAT_MSK = ( 1UL << NTP_PEER_STATE_SUPP_REACH_STAT ), ///< See ::NTP_PEER_STATE_SUPP_REACH_STAT + NTP_PEER_STATE_SUPP_PRECISION_MSK = ( 1UL << NTP_PEER_STATE_SUPP_PRECISION ), ///< See ::NTP_PEER_STATE_SUPP_PRECISION + NTP_PEER_STATE_SUPP_ROOT_DELAY_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ROOT_DELAY ), ///< See ::NTP_PEER_STATE_SUPP_ROOT_DELAY + NTP_PEER_STATE_SUPP_ROOT_DISP_MSK = ( 1UL << NTP_PEER_STATE_SUPP_ROOT_DISP ), ///< See ::NTP_PEER_STATE_SUPP_ROOT_DISP + NTP_PEER_STATE_SUPP_HEADWAY_MSK = ( 1UL << NTP_PEER_STATE_SUPP_HEADWAY ), ///< See ::NTP_PEER_STATE_SUPP_HEADWAY + NTP_PEER_STATE_SUPP_FLASH_STAT_MSK = ( 1UL << NTP_PEER_STATE_SUPP_FLASH_STAT ), ///< See ::NTP_PEER_STATE_SUPP_FLASH_STAT + NTP_PEER_STATE_SUPP_KEY_ID_MSK = ( 1UL << NTP_PEER_STATE_SUPP_KEY_ID ), ///< See ::NTP_PEER_STATE_SUPP_KEY_ID + NTP_PEER_STATE_SUPP_DISP_MSK = ( 1UL << NTP_PEER_STATE_SUPP_DISP ), ///< See ::NTP_PEER_STATE_SUPP_DISP + NTP_PEER_STATE_SUPP_JITTER_MSK = ( 1UL << NTP_PEER_STATE_SUPP_JITTER ), ///< See ::NTP_PEER_STATE_SUPP_JITTER + NTP_PEER_STATE_SUPP_XLEAVE_MSK = ( 1UL << NTP_PEER_STATE_SUPP_XLEAVE ), ///< See ::NTP_PEER_STATE_SUPP_XLEAVE }; + /** * @brief Structure that represents the status of an NTP peer * @@ -10276,7 +20305,7 @@ enum NTP_PEER_STATE_SUPP_FLAG_MASKS * * @see ::NTP_PEER_STATE_IDX */ -typedef struct +typedef struct ntp_peer_state_s { uint32_t supp_flags; ///< Supported NTP peer state values, see ::NTP_PEER_STATE_SUPP_FLAG_MASKS @@ -10292,8 +20321,8 @@ typedef struct uint8_t reserved_1; ///< Reserved, currently always 0 uint16_t reserved_2; ///< Reserved, currently always 0 - MBG_IP_ADDR_PORT src_addr; ///< Source address of the NTP peer, see ::MBG_IP_ADDR_PORT - MBG_IP_ADDR_PORT dst_addr; ///< Destination address of the NTP peer, see ::MBG_IP_ADDR_PORT + MBG_IP_ADDR_PORT src_addr; ///< Source address of the NTP peer, see ::MBG_IP_ADDR_PORT + MBG_IP_ADDR_PORT dst_addr; ///< Destination address of the NTP peer, see ::MBG_IP_ADDR_PORT uint8_t stratum; ///< Current stratum level of the NTP peer int8_t precision; ///< Precision of the peer clock (2^precision) @@ -10302,7 +20331,7 @@ typedef struct int32_t root_delay; ///< [us] Total roundtrip delay to the system peer of the NTP peer int32_t root_disp; ///< [us] Total dispersion to the system peer of the NTP peer - MBG_IP_ADDR ref_id; ///< Reference ID of the NTP peer, see ::MBG_IP_ADDR + MBG_IP_ADDR ref_id; ///< Reference ID of the NTP peer, see ::MBG_IP_ADDR NTP_TSTAMP ref_time; ///< Last time the NTP peers time has been adjusted, see ::NTP_TSTAMP NTP_TSTAMP rec_time; ///< Current system time of the NTP peer, see ::NTP_TSTAMP @@ -10337,7 +20366,75 @@ typedef struct uint32_t reserved_9; ///< Reserved, currently always 0 -} NTP_PEER_STATE; +} NTP_PEER_STATE, NTP_REFCLK_STATE; + + + +#define _mbg_swab_ntp_peer_state( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_flags ); \ + \ + _mbg_swab16( &(_p)->ass_id ); \ + _mbg_swab16( &(_p)->peer_status_flags ); \ + \ + _mbg_swab8( &(_p)->leap_ind ); \ + _mbg_swab8( &(_p)->peer_sel_stat ); \ + _mbg_swab8( &(_p)->peer_evt_cnt ); \ + _mbg_swab8( &(_p)->peer_rec_evt ); \ + \ + _mbg_swab8( &(_p)->peer_reach_stat ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + \ + _mbg_swab_ip_addr_port( &(_p)->src_addr ); \ + _mbg_swab_ip_addr_port( &(_p)->dst_addr ); \ + \ + _mbg_swab8( &(_p)->stratum ); \ + _mbg_swab8( &(_p)->precision ); \ + _mbg_swab16( &(_p)->reserved_3 ); \ + \ + _mbg_swab32( &(_p)->root_delay ); \ + _mbg_swab32( &(_p)->root_disp ); \ + \ + _mbg_swab_ip_addr( &(_p)->ref_id ); \ + \ + _mbg_swab_ntp_tstamp( &(_p)->ref_time ); \ + _mbg_swab_ntp_tstamp( &(_p)->rec_time ); \ + \ + _mbg_swab8( &(_p)->reach ); \ + _mbg_swab8( &(_p)->reserved_4 ); \ + _mbg_swab16( &(_p)->unreach ); \ + \ + _mbg_swab8( &(_p)->host_mode ); \ + _mbg_swab8( &(_p)->peer_mode ); \ + _mbg_swab8( &(_p)->host_poll ); \ + _mbg_swab8( &(_p)->peer_poll ); \ + \ + _mbg_swab8( &(_p)->headway ); \ + _mbg_swab8( &(_p)->reserved_5 ); \ + _mbg_swab16( &(_p)->flash_stat_flags ); \ + \ + _mbg_swab16( &(_p)->key_id ); \ + _mbg_swab16( &(_p)->reserved_6 ); \ + \ + _mbg_swab64( &(_p)->offset ); \ + _mbg_swab64( &(_p)->delay ); \ + \ + _mbg_swab32( &(_p)->disp ); \ + _mbg_swab32( &(_p)->jitter ); \ + \ + _mbg_swab32( &(_p)->xleave ); \ + \ + _mbg_swab8( &(_p)->n_filter_values ); \ + _mbg_swab8( &(_p)->reserved_7 ); \ + _mbg_swab16( &(_p)->reserved_8 ); \ + \ + _mbg_swab32( &(_p)->reserved_9 ); \ + \ +} while ( 0 ) + +#define _mbg_swab_ntp_refclk_state ( _p ) _mbg_swab_ntp_peer_state( _p ) /** @@ -10347,12 +20444,24 @@ typedef struct * * @see ::NTP_PEER_STATE */ -typedef struct +typedef struct ntp_peer_state_idx_s { - uint32_t idx; ///< The index of the observed NTP peer + MBG_MSG_IDX_32 idx; ///< The index of the observed NTP peer NTP_PEER_STATE peer_state; ///< Peer state, see ::NTP_PEER_STATE -} NTP_PEER_STATE_IDX; +} NTP_PEER_STATE_IDX, NTP_REFCLK_STATE_IDX; + + +#define _mbg_swab_ntp_peer_state_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_ntp_peer_state( &(_p)->peer_state ); \ +} while ( 0 ) + + +#define _mbg_swab_ntp_refclk_state_idx( _p ) _mbg_swab_ntp_peer_state_idx( _p ) + /** @} defgroup group_ntp */ @@ -10366,7 +20475,7 @@ typedef struct #define MAX_LNO_OUTPUT 4 /** - * @brief LNO status + * @brief LNO state */ typedef struct { @@ -10382,6 +20491,7 @@ typedef struct } LNO_STATE; #define _mbg_swab_lno_state( _p ) \ +do \ { \ int i; \ \ @@ -10391,11 +20501,11 @@ typedef struct _mbg_swab_16( &(_p)->max_sine_lvl ); \ _mbg_swab_16( &(_p)->reserved_0 ); \ _mbg_swab_16( &(_p)->flags ); \ -} +} while ( 0 ) /** - * @brief Flags used with LNO_STATE::flags + * @brief Flags used with ::LNO_STATE::flags */ enum LNO_STATE_FLAG_BITS { @@ -10444,12 +20554,13 @@ typedef struct } VST_HEADER; #define _mbg_swab_vst_header( _p ) \ +do \ { \ _mbg_swab16( &(_p)->data_type ); \ _mbg_swab16( &(_p)->idx ); \ _mbg_swab16( &(_p)->data_len ); \ _mbg_swab16( &(_p)->reserved ); \ -} +} while ( 0 ) /** @} defgroup group_vst */ @@ -10497,17 +20608,18 @@ typedef struct NANO_TIME err_limit; ///< time difference limit above which an error is indicated NANO_TIME warn_limit; ///< time difference limit above which a warning is indicated uint32_t reserved; ///< reserved, currently always 0 - uint32_t flags; ///< see ::SHS_FLAG_MASKS + uint32_t flags; ///< See ::SHS_FLAG_MASKS } SHS_SETTINGS; #define _mbg_swab_shs_settings( _p ) \ +do \ { \ _mbg_swab_nano_time( &(_p)->err_limit ); \ _mbg_swab_nano_time( &(_p)->warn_limit ); \ _mbg_swab32( &(_p)->reserved ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) @@ -10527,12 +20639,13 @@ typedef struct } SHS_INFO; #define _mbg_swab_shs_info( _p ) \ +do \ { \ _mbg_swab_shs_settings( &(_p)->settings ); \ _mbg_swab_nano_time( &(_p)->max_limit ); \ _mbg_swab32( &(_p)->reserved ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) @@ -10541,24 +20654,25 @@ typedef struct */ typedef struct { - NANO_TIME time_diff; ///< current time difference between the 2 clocks - TM_STATUS_EXT clk_status_1; ///< status of first clock - TM_STATUS_EXT clk_status_2; ///< status of second clock - uint8_t shs_state; ///< see ::SHS_STATES - uint8_t reserved_1; ///< reserved, currently always 0 - uint16_t reserved_2; ///< reserved, currently always 0 - uint32_t flags; ///< see ::SHS_FLAG_MASKS + NANO_TIME time_diff; ///< Current time difference between the 2 clocks. + TM_GPS_STATUS_EXT clk_status_1; ///< Status of first clock. + TM_GPS_STATUS_EXT clk_status_2; ///< Status of second clock. + uint8_t shs_state; ///< See ::SHS_STATES. + uint8_t reserved_1; ///< Reserved, currently always 0. + uint16_t reserved_2; ///< Reserved, currently always 0. + uint32_t flags; ///< See ::SHS_FLAG_MASKS. } SHS_STATUS; #define _mbg_swab_shs_status( _p ) \ +do \ { \ _mbg_swab_nano_time( &(_p)->time_diff ); \ _mbg_swab32( &(_p)->clk_status_1 ); \ _mbg_swab32( &(_p)->clk_status_2 ); \ _mbg_swab16( &(_p)->reserved_2 ); \ _mbg_swab32( &(_p)->flags ); \ -} +} while ( 0 ) @@ -10602,21 +20716,625 @@ enum SHS_FLAG_BITS * tool in ::SHS_SETTINGS::flags to enable the associated feature. * If a corresponding bit is set in ::SHS_STATUS::flags this means the * associated feature has been enabled, e.g. an action has been taken. - * + * * @see ::SHS_FLAG_BITS */ enum SHS_FLAG_MASKS { - SHS_FLAG_DISB_SERIAL = ( 1UL << SHS_FLAG_BIT_DISB_SERIAL ), ///< see ::SHS_FLAG_BIT_DISB_SERIAL - SHS_FLAG_DISB_PPS = ( 1UL << SHS_FLAG_BIT_DISB_PPS ), ///< see ::SHS_FLAG_BIT_DISB_PPS - SHS_FLAG_DISB_10MHZ = ( 1UL << SHS_FLAG_BIT_DISB_10MHZ ) ///< see ::SHS_FLAG_BIT_DISB_10MHZ + SHS_FLAG_DISB_SERIAL = ( 1UL << SHS_FLAG_BIT_DISB_SERIAL ), ///< See ::SHS_FLAG_BIT_DISB_SERIAL + SHS_FLAG_DISB_PPS = ( 1UL << SHS_FLAG_BIT_DISB_PPS ), ///< See ::SHS_FLAG_BIT_DISB_PPS + SHS_FLAG_DISB_10MHZ = ( 1UL << SHS_FLAG_BIT_DISB_10MHZ ) ///< See ::SHS_FLAG_BIT_DISB_10MHZ }; /** @} defgroup group_shs */ -/*------------------------------------------------------------------------*/ +/** + * @defgroup group_xbp eXtended Binary Protocol definitions + * + * @note These structures are only supported if ::GPS_HAS_XBP is set + * in ::RECEIVER_INFO::features. + * + * @{ */ + +/** + * @brief An XBP port specifier + * + * Each controller can provide up to 255 ports with numbers 0..254. + * XBP port number ::XBP_PORT_RESERVED is reserved to mark unused ports. + */ +typedef uint8_t XBP_PORT; + + +/** + * @brief An identifier used to mark an XBP port unused + */ +#define XBP_PORT_RESERVED ( (XBP_PORT) -1 ) + + +/** + * @brief Maximum XBP bus/controller cascading level + * + * Should be 7 so the total size of ::XBP_ADDR is 8 bytes. + */ +#define MAX_XBP_CASC_LVL 7 + + +/** + * @brief An XBP address specifier + * + * A generic scheme to address devices connected to cascaded controllers. + */ +typedef struct xbp_addr_s +{ + uint8_t hop_count; ///< Used as index to the addr array + XBP_PORT addr[MAX_XBP_CASC_LVL]; ///< An array of port numbers on cascaded controllers + +} XBP_ADDR; + +#define _mbg_swab_xbp_addr( _p ) _nop_macro_fnc() // only single bytes + + + +/** + * @brief A structure used to report XBP features and limits + */ +typedef struct +{ + uint32_t features; ///< Mask of XBP features, see ::XBP_FEAT_MASKS + uint32_t flags; ///< XBP flags, currently not used + uint32_t reserved_0; ///< reserved, currently not used + uint32_t reserved_1; ///< reserved, currently not used + uint32_t reserved_2; ///< reserved, currently not used + uint32_t reserved_3; ///< reserved, currently not used + +} XBP_LIMITS; + +#define _mbg_swab_xbp_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->features ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of bits used to define ::XBP_FEAT_MASKS + */ +enum XBP_FEAT_BITS +{ + XBP_FEAT_BIT_NODES, ///< Supports ::XBP_NODE_LIMITS and associated structures + N_XBP_FEAT_BITS +}; + + +/** + * @brief XBP feature masks used with ::XBP_LIMITS::features + * + * @see ::XBP_FEAT_BITS + */ +enum XBP_FEAT_MASKS +{ + XBP_FEAT_MASK_NODES = ( 1UL << XBP_FEAT_BIT_NODES ) ///< See ::XBP_FEAT_BIT_NODES +}; + + + +/** + * @brief Information on available XBP nodes + * + * Only supported if ::XBP_FEAT_MASK_NODES is set in ::XBP_LIMITS::features. + */ +typedef struct +{ + uint32_t node_count; ///< Number of XBP nodes available in the system + uint32_t reserved_0; ///< Currently reserved, always 0 + uint32_t reserved_1; ///< Currently reserved, always 0 + // TODO: do we need additional fields here? + +} XBP_NODE_LIMITS; + +#define _mbg_swab_xbp_node_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->node_count ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Possible states of an XBP device + * + * Used with ::XBP_NODE_INFO::state. + */ +enum XBP_DEVICE_STATES +{ + XBP_DEVICE_STATE_UNKNOWN, + XBP_DEVICE_STATE_NOT_AVAILABLE, + XBP_DEVICE_STATE_INITIALIZING, + XBP_DEVICE_STATE_AVAILABLE, + XBP_DEVICE_STATE_DISCONNECTED, + XBP_DEVICE_STATE_OUTDATED, + N_XBP_DEVICE_STATES +}; + + +/** + * @brief Possible IMS slot types of an XBP device + * + * Used with ::XBP_NODE_INFO::slot_type. + */ +enum XBP_SLOT_TYPES +{ + XBP_SLOT_TYPE_UNKNOWN, ///< Unknown slot type, i.e. slot type not supp. + XBP_SLOT_TYPE_PWR, ///< Slot for power supply units + XBP_SLOT_TYPE_CLK, ///< Slot for reference clocks + XBP_SLOT_TYPE_SCU, ///< Slot for switch card units + XBP_SLOT_TYPE_CPU, ///< Slot for processing units + XBP_SLOT_TYPE_MRI, ///< Slot for MRI (multi reference input) cards + XBP_SLOT_TYPE_ESI, ///< Slot for ESI (extended reference input) cards + XBP_SLOT_TYPE_IO, ///< Slot for all other input/output cards + N_XBP_SLOT_TYPES +}; + + +#define XBP_SLOT_TYPE_STRS \ +{ \ + "Unknown", \ + "PWR", \ + "CLK", \ + "SCU", \ + "CPU", \ + "MRI", \ + "ESI", \ + "IO" \ +} + + +/// Maximum string length (including terminating zero) of a full XBP slot name +/// which consists of ::XBP_NODE_INFO::slot_type and ::XBP_NODE_INFO::slot_type_id +/// Examples: "CLK1", "MRI2", ... +#define XBP_MAX_SLOT_NAME 5 + + +/** + * @brief Information on a specific XBP node + * + * Only supported if ::XBP_FEAT_MASK_NODES is set in ::XBP_LIMITS::features. + * The number of instances supported by a device is specified + * in ::XBP_NODE_LIMITS::node_count. + */ +typedef struct xbp_node_info_s +{ + XBP_ADDR addr; ///< The address of the specific node + + /// @brief ::RECEIVER_INFO of the device connected to this node. + /// + /// If no device is available then ::RECEIVER_INFO::model_code + /// is set to ::GPS_MODEL_UNKNOWN (== 0). + RECEIVER_INFO ri; + + uint8_t state; ///< The device state, see ::XBP_DEVICE_STATES + + uint8_t slot_type; ///< The IMS slot type, see ::XBP_SLOT_TYPES + uint8_t slot_type_id; ///< ID depending on the ::XBP_NODE_INFO::slot_type, i.e. 1 for CLK1 + + uint8_t reserved; ///< Currently reserved, always 0 + uint16_t flags; ///< Currently reserved, always 0 + +} XBP_NODE_INFO; + +#define _mbg_swab_xbp_node_info( _p ) \ +do \ +{ \ + _mbg_swab_xbp_addr( &(_p)->addr ); \ + _mbg_swab_receiver_info( &(_p)->ri ); \ + _mbg_swab8( &(_p)->state ); \ + _mbg_swab8( &(_p)->slot_type ); \ + _mbg_swab8( &(_p)->slot_type_id ); \ + _mbg_swab8( &(_p)->reserved ); \ + _mbg_swab16( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Information on an XBP node with specific index + * + * Only supported if ::XBP_FEAT_MASK_NODES is set in ::XBP_LIMITS::features. + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; ///< node index, 0..::XBP_NODE_LIMITS::node_count-1 + XBP_NODE_INFO node_info; ///< ::RECEIVER_INFO of the device behind this node + +} XBP_NODE_INFO_IDX; + +#define _mbg_swab_xbp_node_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_xbp_node_info( &(_p)->node_info ); \ +} while ( 0 ) + + +/** @} defgroup group_xbp */ + + + +/** + * @defgroup group_tlv_api Meinberg TLV API definitions + * + * @note These structures and definitions are only supported by a device + * if ::MBG_XFEATURE_TLV_API is set in the extended device features. + * + * @{ */ + + +/** + * @brief A data type used to hold a unique ID (UID) for a TLV transaction + */ +typedef uint32_t MBG_TLV_UID; + +#define _mbg_swab_tlv_uid( _p ) \ + _mbg_swab32( _p ) + + + +/** + * @brief A data type to hold one of the ::MBG_TLV_TYPES or ::MBG_TLV_FEAT_TYPES + * + * @see ::MBG_TLV_TYPES + * @see ::MBG_TLV_FEAT_TYPES + */ +typedef uint32_t MBG_TLV_TYPE; + +#define _mbg_swab_tlv_type( _p ) \ + _mbg_swab32( _p ) + + + +/** + * @defgroup group_tlv_feat Meinberg TLV feature definitions + * + * @{ */ + + +/** + * @brief The maximum number of TLV feature types. + * + * Warning: Changing this number breaks API compatibility! + * + * @see ::MBG_TLV_FEAT_TYPES + */ +#define MAX_MBG_TLV_FEAT_TYPES 128 //### TODO Is this sufficient? + + +/** + * @brief Enumeration of known TLV feature types. + * + * TLV feature types are used to specify the content of a binary TLV message + * so that the receiver knows how to interpret the content. + * + * Used with ::MBG_TLV_INFO::supp_tlv_feat and ::MBG_TLV_DATA::type. ### TODO + * + * @see ::MBG_TLV_FEAT_BUFFER + * @see ::MBG_TLV_FEAT_TYPE_NAMES + * @see ::MBG_TLV_TYPES + * @see ::MBG_TLV_TYPE + */ +enum MBG_TLV_FEAT_TYPES +{ + /// Expects two TLV types in order: + /// 1) ::MBG_TLV_TYPE_STR => Firmware version as string + /// 2) ::MBG_TLV_TYPE_FILE => Firmware file as data blob + MBG_TLV_FEAT_TYPE_FW_UPDATE, + + /// If the total bytes of aan announce message is 0, it is a diagnostics file + /// request. If the total bytes are not 0, TLV type ::MBG_TLV_TYPE_FILE + /// is expected and it should contain a file as data blob. + MBG_TLV_FEAT_TYPE_DIAG_FILE, + + /// Only used as action trigger on a remote site, expects no data. + MBG_TLV_FEAT_TYPE_FW_ROLLBACK, + + /// Expects two TLV types in order: + /// 1) ::MBG_TLV_TYPE_STR => Full qualified path including filename on target system + /// 2) ::MBG_TLV_TYPE_FILE => File as data blob + MBG_TLV_FEAT_TYPE_FILE_TRANSFER, + + /// 1) ::MBG_TLV_TYPE_STR => Command line call as string + MBG_TLV_FEAT_TYPE_EXEC_CMD, + + /// 1) ::MBG_TLV_TYPE_FILE => Encrypted license file as data blob + MBG_TLV_FEAT_TYPE_LICENSE_UPGRADE, + + /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_LIMITS, see @ref group_license_limits + MBG_TLV_FEAT_TYPE_LICENSE_LIMITS, + + /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_PTPV2_IDX, see @ref group_license_limits + MBG_TLV_FEAT_TYPE_LICENSE_PTPV2_IDX, + + /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_NTP_IDX, see @ref group_license_limits + MBG_TLV_FEAT_TYPE_LICENSE_NTP_IDX, + + /// Expects two TLV types in order: + /// 1) ::MBG_TLV_TYPE_STR => Full qualified path including filename on target system + MBG_TLV_FEAT_TYPE_FILE_REQUEST, + + /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_PTPV1_IDX, see @ref group_license_limits + MBG_TLV_FEAT_TYPE_LICENSE_PTPV1_IDX, + + /// 1) ::MBG_TLV_TYPE_BLOB => ::MBG_LICENSE_TIME_MONITOR_IDX, see @ref group_license_limits + MBG_TLV_FEAT_TYPE_LICENSE_TIME_MONITOR_IDX, + + /// used to receive full TimeMon Status structure + MBG_TLV_FEAT_TYPE_TIMEMON_FULL_STATUS, + + /// 1) ::MBG_TLV_TYPE_BLOB => Unified Firmware Update (UFU) file, see mbg_ufu.h + MBG_TLV_FEAT_TYPE_UFU, + + N_MBG_TLV_FEAT_TYPES + // NOTE If new TLV feature types are appended here then an appropriate + // name string has to be appended to ::MBG_TLV_FEAT_TYPE_NAMES, and care must + // be taken that ::N_MBG_TLV_FEAT_TYPES doesn't exceed ::MAX_MBG_TLV_FEAT_TYPES. +}; + + +/** + * @brief Names of TLV API features + * + * Can be used to initialize a string array of ::N_MBG_TLV_FEAT_TYPES entries, + * so the number of strings must correspond to ::N_MBG_TLV_FEAT_TYPES. + * + * @see ::MBG_TLV_FEAT_TYPES + */ +#define MBG_TLV_FEAT_TYPE_NAMES \ +{ \ + "TLV Firmware Update", \ + "TLV Diagnostics File", \ + "TLV Firmware Rollback", \ + "TLV File Transfer", \ + "TLV Execute Command", \ + "TLV License Upgrade", \ + "TLV License Limits", \ + "TLV License PTPV2", \ + "TLV License NTP", \ + "TLV File Request", \ + "TLV License PTPV1 IDX", \ + "TLV License Sync Monitor", \ + "TLV Sync Monitor Full Status", \ + "TLV Unified Firmware Update" \ +} + + + +/** + * @brief Array size required to store up to ::MAX_MBG_TLV_FEAT_TYPES bits + * + * The number of bytes required to store up to ::MAX_MBG_TLV_FEAT_TYPES + * feature bits in a byte array. + */ +#define MAX_MBG_TLV_FEAT_BYTES ( MAX_MBG_TLV_FEAT_TYPES / 8 ) + + +/** + * @brief A structure used to store a bit mask of supported TLV context types. + * + * Bit masks for up to ::MAX_MBG_TLV_FEAT_TYPES totally can be stored, + * but only ::N_MBG_TLV_FEAT_TYPES types are currently defined. + * The ::_set_tlv_feat_bit macro should be used by the firmware + * to set a bit mask in the buffer, and the ::check_tlv_feat_supp + * function should be used to implement API calls which test if an + * extended TLV context type is supported. + * + * @see ::_set_tlv_feat_bit + * @see ::check_tlv_feat_supp + */ +typedef struct +{ + uint8_t b[MAX_MBG_TLV_FEAT_BYTES]; + +} MBG_TLV_FEAT_BUFFER; + + + +/** + * @brief Set a TLV context type bit in a ::MBG_TLV_FEAT_BUFFER + * + * Should be used by the firmware only to set one of the ::MBG_TLV_FEAT_TYPES + * bits in an ::MBG_TLV_FEAT_BUFFER after power-up. + * + * @param[in] _tlv_feat_type One of the ::MBG_TLV_FEAT_TYPES + * @param[in] _tlv_feat_buffp Pointer to a ::MBG_TLV_FEAT_BUFFER + */ +#define _set_tlv_feat_bit( _tlv_feat_type, _tlv_feat_buffp ) \ + _set_array_bit( _tlv_feat_type, (_tlv_feat_buffp)->supp_tlv_feat.b, MAX_MBG_TLV_FEAT_BYTES ) + + +/** @} defgroup group_tlv_feat */ + + + +/** + * @brief A structure used to query current TLV capabilities + * + * This is only supported by a device if the ::MBG_XFEATURE_TLV_API bit + * is set in the extended device features. + */ +typedef struct +{ + uint32_t reserved; ///< Future use + uint32_t flags; ///< Future use + MBG_TLV_FEAT_BUFFER supp_tlv_feat; ///< A byte array of supported TLV feature bits, see ::MBG_TLV_FEAT_TYPES + +} MBG_TLV_INFO; + +#define _mbg_swab_tlv_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Enumeration of known TLV types + * + * Used with ::MBG_TLV_TYPE types, e.g. in ::MBG_TLV_HDR::tlv_type + * or ::MBG_TLV_DATA::type. + * + * @see ::MBG_TLV_FEAT_TYPES + * @see ::MBG_TLV_TYPE + */ +enum MBG_TLV_TYPES +{ + MBG_TLV_TYPE_STR, + MBG_TLV_TYPE_FILE, + MBG_TLV_TYPE_BLOB, ///< In fact, a file is also a blob but + ///< give the child a different name to avoid confusion. + ///< Use this for getting/setting fixed structures! + N_MBG_TLV_TYPES +}; + + + +/** + * @brief General TLV data structure + * + * Structure containing common, additional data required to send + * an announce message for following TLVs. + */ +typedef struct +{ + MBG_TLV_UID uid; ///< Unique ID identifying following TLVs, 0 if empty/not set. + MBG_TLV_TYPE type; ///< One of the ::MBG_TLV_TYPES or ::MBG_TLV_FEAT_TYPES depending on the type of message. + uint32_t total_bytes; ///< Number of all bytes including header(s) that are related to a TLV block transaction. + uint32_t reserved_1; ///< Reserved for future use + +} MBG_TLV_DATA; + +#define _mbg_swab_tlv_data( _p ) \ +do \ +{ \ + _mbg_swab_tlv_uid( &(_p)->uid ); \ + _mbg_swab_tlv_type( &(_p)->type ); \ + _mbg_swab32( &(_p)->total_bytes ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Structure containing state information while reading TLV data. + */ +typedef struct +{ + MBG_TLV_DATA data; ///< See ::MBG_TLV_DATA + uint32_t read_bytes; ///< Number of bytes read + uint32_t reserved_1; ///< Future use + +} MBG_TLV_RCV_STATE; + + + +/** + * @brief A structure initiating a TLV transfer + * + * ::MBG_TLV_ANNOUNCE should be sent first, before starting a + * TLV transfer, to inform the remote site about following TLVs. + * Following sequence of TLVs is not fixed and implementation + * dependent. + */ +typedef struct +{ + MBG_TLV_DATA data; ///< See ::MBG_TLV_DATA + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + +} MBG_TLV_ANNOUNCE; + +#define _mbg_swab_tlv_announce( _p ) \ +do \ +{ \ + _mbg_swab_tlv_data( &(_p)->data ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +#define MSG_TLV_MAX_VALUE_SIZE 480 + +/** + * @brief TLV header structure containing information on current TLV transaction + */ +typedef struct +{ + MBG_TLV_UID uid; ///< Unique source ID. See ::MBG_TLV_DATA::uid + MBG_TLV_UID tlv_type; ///< "Subtype" identifying current TLV, see ::MBG_TLV_TYPES + uint32_t cur_bytes; ///< Number of bytes in ::MBG_TLV::value + uint32_t trans_bytes; ///< Number of bytes transferred so far related to this TLV type. + uint32_t total_bytes; ///< Number of total bytes (size) of this TLV type without header. + ///< It is fixed and must not be changed during a TLV transaction. + uint32_t reserved_1; ///< Future use + uint32_t reserved_2; ///< Future use + uint32_t reserved_3; ///< Future use + +} MBG_TLV_HDR; + +#define _mbg_swab_tlv_header( _p ) \ +do \ +{ \ + _mbg_swab_tlv_uid( &(_p)->uid ); \ + _mbg_swab_tlv_type( &(_p)->tlv_type ); \ + _mbg_swab32( &(_p)->cur_bytes ); \ + _mbg_swab32( &(_p)->trans_bytes ); \ + _mbg_swab32( &(_p)->total_bytes ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ +} while ( 0 ) + + + +/** + * @brief TLV structure containing information on current TLV transaction and its current data. + */ +typedef struct +{ + MBG_TLV_HDR hdr; ///< See ::MBG_TLV_HDR + uint8_t value[MSG_TLV_MAX_VALUE_SIZE]; ///< See ::MSG_TLV_MAX_VALUE_SIZE + +} MBG_TLV; + +#define _mbg_swab_tlv( _p ) \ +do \ +{ \ + _mbg_swab_tlv_header( &(_p)->hdr ); \ +} while ( 0 ) + +/** @} defgroup group_tlv_api */ + + + +/** + * @defgroup group_gps_nav_data Definitions used with navigational data received from GPS satellites + * + * @note These structures and definitions are only supported by a device + * if ::GPS_MODEL_IS_GPS is set in the @ref GPS_BUILTIN_FEATURE_MASKS + * + * @{ */ + /** * @brief Ephemeris parameters of one specific satellite @@ -10710,8 +21428,8 @@ typedef struct T_GPS tot_63; ///< time of transmission, page 63 T_GPS t0a; ///< complete reference time almanac - CFG cfg[N_SVNO_GPS]; ///< SV configuration from page 63 - HEALTH health[N_SVNO_GPS]; ///< SV health from pages 51, 63 + CFG cfg[N_SVNO_GPS]; ///< 4 bit SV configuration code from page 63 + HEALTH health[N_SVNO_GPS]; ///< 6 bit SV health codes from pages 51, 63 } CFGH; @@ -10722,7 +21440,7 @@ typedef struct * * %UTC correction parameters basically as sent by the GPS satellites. * - * The csum field is only used by the card's firmware to check the + * The csum field is only used by the device firmware to check the * consistency of the structure in non-volatile memory. * * The field labeled valid indicates if the parameter set is valid, i.e. @@ -10740,35 +21458,46 @@ typedef struct * after the next leap second event defined by WNlsf and DNt. * * The fields WNlsf and DNt specify the GPS week number and the day number - * in that week at the end of which a leap second is scheduled. + * in that week for the end of which a leap second has been scheduled. * * @note: The satellites transmit WNlsf only as a signed 8 bit value, so it - * can only define a point in time which is ± 127 weeks off the current time. + * can only define a point in time which is +/- 127 weeks off the current time. * The firmware tries to expand this based on the current week number, but * the result is ambiguous if the leap second occurs or occurred more * than 127 weeks in the future or past. * - * So the leap second date should only be evaluated if the fields delta_tls - * and delta_tlsf are different, in which case there is an actual leap second - * announcement inside the ± 127 week range. + * So the leap second date should <b>only</b> be evaluated and displayed + * in a user interface if the fields delta_tls and delta_tlsf have + * different values, in which case there is indeed a leap second announcement + * inside the +/- 127 week range. */ typedef struct { - CSUM csum; ///< Checksum of the remaining bytes - int16_t valid; ///< Flag indicating %UTC parameters are valid + CSUM csum; ///< Checksum of the remaining bytes. + int16_t valid; ///< Flag indicating %UTC parameters are valid. + + T_GPS t0t; ///< Reference Time of %UTC Parameters @a A0 and @a A1 [wn|sec]. + double A0; ///< +- Clock Correction Coefficient 0 [sec]. + double A1; ///< +- Clock Correction Coefficient 1 [sec/sec]. + + GPS_WNUM WNlsf; ///< Week number of nearest leap second, originally + ///< truncated to 8 bit, so the extended number can be + ///< ambiguous unless @a #delta_tls and @a #delta_tlsf + ///< differ, indicating that a leap second is actually + ///< being announced. + + GPS_DNUM DNt; ///< The day-of-week at the end of which a leap second occurs. + ///< Transmitted numbers in the range 1..7 rather than 0..6. - T_GPS t0t; ///< Reference Time %UTC Parameters [wn|sec] - double A0; ///< +- Clock Correction Coefficient 0 [sec] - double A1; ///< +- Clock Correction Coefficient 1 [sec/sec] + int8_t delta_tls; ///< Current %UTC offset to GPS system time [sec]. - uint16_t WNlsf; ///< Week number of nearest leap second - int16_t DNt; ///< The day number at the end of which a leap second occurs - int8_t delta_tls; ///< Current %UTC offset to GPS system time [sec] - int8_t delta_tlsf; ///< Future %UTC offset to GPS system time after next leap second transition [sec] + int8_t delta_tlsf; ///< Future %UTC offset to GPS system time + ///< after next leap second transition [sec]. } UTC; #define _mbg_swab_utc_parm( _p ) \ +do \ { \ _mbg_swab_csum( &(_p)->csum ); \ _mbg_swab16( &(_p)->valid ); \ @@ -10777,7 +21506,7 @@ typedef struct _mbg_swab_double( &(_p)->A1 ); \ _mbg_swab16( &(_p)->WNlsf ); \ _mbg_swab16( &(_p)->DNt ); \ -} +} while ( 0 ) @@ -10814,6 +21543,8 @@ typedef struct } ASCII_MSG; +/** @} defgroup group_gps_nav_data */ + enum GPS_PLATFORMS @@ -10871,6 +21602,7 @@ typedef struct } NAV_TIME_MODE_SETTINGS; + /** * Navigation Engine settings to set configuration * parameters of a dynamic platform model. @@ -10890,6 +21622,5867 @@ typedef struct } NAV_ENGINE_SETTINGS; + +/** + * @defgroup group_sys_ref Reference system configuration + * + * System-wide reference configuration as replacement for XMR to provide an + * improved global API for new meinbergOS systems. + * + * This API is only supported if ::MBG_XFEATURE_SYS_REF is set. + */ + +typedef struct mbg_sys_ref_limits_s +{ + uint32_t num_ref_srcs; ///< Number of reference sources supported by the system, see ::MBG_SYS_REF_SRC_INFO_IDX + uint8_t max_prios; + uint8_t reserved_1[3]; + + uint32_t reserved_2[14]; ///< Reserved, currently always 0 + +} MBG_SYS_REF_LIMITS; + + +#define _mbg_swab_sys_ref_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->num_ref_srcs ); \ + _mbg_swab32( &(_p)->supp_ref_types ); \ +} while ( 0 ) + + +enum MBG_SYS_REF_SRC_FLAGS +{ + SYS_REF_SRC_FLAG_XMR_STATS_SUPP, ///< Indicates, whether XMR stats are supported, read-only + SYS_REF_SRC_FLAG_XMR_ADV_METRICS_SUPP, ///< Indicates, whether advanced XMR metrics are supported, read-only + ///< Refers to the adv. metrics XMR feature, see ::XMR_EXT_SRC_FEAT_FLAG_BIT_ADV_METRICS + SYS_REF_SRC_FLAG_XMR_COASTING_SUPP, ///< Indicates, whether XMR coasting is supported, read-only + N_SYS_REF_SRC_FLAGS +}; + + +enum MBG_SYS_REF_SRC_MASKS +{ + SYS_REF_SRC_MASK_XMR_STATS_SUPP = ( 1UL << SYS_REF_SRC_FLAG_XMR_STATS_SUPP ), ///< See ::SYS_REF_SRC_FLAG_XMR_STATS_SUPP + SYS_REF_SRC_MASK_XMR_ADV_METRICS_SUPP = ( 1UL << SYS_REF_SRC_FLAG_XMR_ADV_METRICS_SUPP ), ///< See ::SYS_REF_SRC_FLAG_XMR_ADV_METRICS_SUPP + SYS_REF_SRC_MASK_XMR_COASTING_SUPP = ( 1UL << SYS_REF_SRC_FLAG_XMR_COASTING_SUPP ) ///< See ::SYS_REF_SRC_FLAG_XMR_COASTING_SUPP +}; + + +enum MBG_SYS_REF_SRC_TYPES +{ + SYS_REF_SRC_INTEGRATED, ///< Integrated reference source, i.e. an SMA or BNC port on the module itself + SYS_REF_SRC_PERIPHERAL, ///< Peripheral reference source, i.e. a port on an MRI (expansion) module + ///< Can only be used, if the equivalent ::SYS_REF_SRC_EXPANSION is equipped + SYS_REF_SRC_EXPANSION, ///< Expansion reference source announced by peripheral modules (i.e. MRI) + ///< Can only be used, if the equivalent ::SYS_REF_SRC_PERIPHERAL has been announced by the clock module + SYS_REF_SRC_AUTARKIC, ///< Autarkic reference source measuring a distinct offset, i.e. an ESI or a PTP (HPS) module + N_SYS_REF_SRC_TYPES +}; + + +#define SYS_REF_SRC_PRIO_UNUSED 0xFF +#define SYS_REF_SRC_INFO_STR_LEN 32 + +#define SYS_REF_SRC_PRQ_UNQUANTIFIED (-1) + +typedef struct mbg_sys_ref_src_settings_s +{ + uint8_t prio; ///< Priority for this reference + ///< must be 0 .. ::MBG_SYS_REF_LIMITS::num_ref_srcs or ::SYS_REF_SRC_PRIO_UNUSED + uint8_t itu_mask; ///< Used mask for ::XMR_METRICS, see ::MBG_SYS_REF_SRC_INFO::supp_itu_masks, only valid if + ///< ::SYS_REF_SRC_MASK_XMR_ADV_METRICS_SUPP is set in ::MBG_SYS_REF_SRC_INFO::supp_flags + uint8_t hysteresis; ///< Hysteresis (percent) between yellow and red alarm for ::XMR_METRICS, only valid if + ///< ::SYS_REF_SRC_MASK_XMR_ADV_METRICS_SUPP is set in ::MBG_SYS_REF_SRC_INFO::supp_flags + uint8_t reserved; ///< Reserved, currently always 0 + + uint32_t xmr_flags; ///< See ::XMR_SETTINGS_FLAG_MSKS + + NANO_TIME bias; ///< time bias, e.g. path delay + NANO_TIME precision; ///< precision of the time source + + uint32_t ro_uid; ///< Read-Only unique ref source identifier. We desperately + ///< need it to not be index dependent when sending settings. + ///< Layout from MSB to LSB: + ///< 8 bit chassis Id - 8 bit slot ID - 8 bit ref type (::MULTI_REF_TYPES) - 8 bit instance number (::XMULTI_REF_INSTANCES::n_inst[ref type]) + + int8_t quantifier; ///< Source precision quantifier (PRQ) to minimize clock switching operations, see ::SYS_REF_SRC_PRQ_UNQUANTIFIED. + ///< The smaller the value the more important is this source in relation to other sources (priorities). + uint8_t reserved_1[3]; + + uint32_t reserved_2[8]; ///< Reserved, currently always 0 + +} MBG_SYS_REF_SRC_SETTINGS; + + +/** + * @brief Default initializer for ::MBG_SYS_REF_SRC_SETTINGS::quantifier and the corresponding ::MULTI_REF_TYPES + * in ::XMULTI_REF_INSTANCES::n_inst. Keep them in sync! + */ +#define SYS_REF_SRC_QUANTIFIERS \ +{ \ + 0, 1, 1, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + 4, 6, 2, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + 1, 3, 3, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + 6, 6, 0, 3, \ + 5, 2, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, \ + SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED, SYS_REF_SRC_PRQ_UNQUANTIFIED \ +} + + +#define __to_sys_ref_ro_uid(c, s, t, i) \ + (((uint32_t)(c) << 24) | \ + ((uint32_t)(s) << 16) | \ + ((uint32_t)(t) << 8) | \ + ((uint32_t)(i))) + + +#define _mbg_swab_sys_ref_src_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->xmr_flags ); \ + _mbg_swab_nano_time( &(_p)->bias ); \ + _mbg_swab_nano_time( &(_p)->precision ); \ + _mbg_swab32( &(_p)->ro_uid ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SYS_REF_SRC_SETTINGS settings; + +} MBG_SYS_REF_SRC_SETTINGS_IDX; + + +#define _mbg_swab_sys_ref_src_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_sys_ref_src_settings( &(_p)->settings ); \ +} while ( 0 ) + + +#define SYS_REF_SRC_PORT_UNKNOWN 0xFF + + +typedef struct mbg_sys_ref_src_info_s +{ + MBG_SYS_REF_SRC_SETTINGS settings; ///< See ::MBG_SYS_REF_SRC_SETTINGS + + uint8_t ref_type; ///< See ::MULTI_REF_TYPES + uint8_t conn_type; ///< See ::MBG_SYS_REF_SRC_TYPES + uint8_t clock_idx; ///< Index of the associated clock, if #conn_type is ::SYS_REF_SRC_PERIPHERAL, resp. ::SYS_REF_SRC_EXPANSION + uint8_t chassis_idx; ///< Index of the associated IMS chassis, or ::MBG_OWN_EVENT_CHASSIS + + uint8_t slot_type; ///< See ::XBP_NODE_INFO::slot_type, or ::MBG_OWN_EVENT_SLOT_TYPE + uint8_t slot_type_id; ///< See ::XBP_NODE_INFO::slot_type_id, or ::MBG_OWN_EVENT_SLOT_TYPE_ID + uint8_t port_idx; ///< Index of the associated physical port (I/O port), or ::SYS_REF_SRC_PORT_UNKNOWN. + uint8_t inst_num; ///< Instance number of ref_type in slot. See ::XMULTI_REF_INSTANCES::n_inst + + char str[SYS_REF_SRC_INFO_STR_LEN]; ///< String for reference identification + + uint32_t supp_xmr_flags; ///< See ::XMR_SETTINGS_FLAG_MSKS + uint32_t supp_flags; ///< See ::MBG_SYS_REF_SRC_INFO::supp_flags and ::MBG_SYS_REF_SRC_MASKS + uint32_t supp_itu_masks; ///< See ::ITU_LIMIT_MASKS + uint32_t reserved_2[7]; ///< Reserved, currently always 0 + +} MBG_SYS_REF_SRC_INFO; + + +#define _mbg_swab_sys_ref_src_info( _p ) \ +do \ +{ \ + _mbg_swab_sys_ref_src_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_xmr_flags ); \ + _mbg_swab32( &(_p)->supp_itu_masks ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SYS_REF_SRC_INFO info; + +} MBG_SYS_REF_SRC_INFO_IDX; + + +#define _mbg_swab_sys_ref_src_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_sys_ref_src_info( &(_p)->info ); \ +} while ( 0 ) + + + +enum MBG_EST_TIME_QUALITY +{ + MBG_EST_TIME_QUALITY_RES_1, + MBG_EST_TIME_QUALITY_RES_2, + MBG_EST_TIME_QUALITY_RES_3, + MBG_EST_TIME_QUALITY_1ns, + MBG_EST_TIME_QUALITY_10ns, + MBG_EST_TIME_QUALITY_25ns, + MBG_EST_TIME_QUALITY_100ns, + MBG_EST_TIME_QUALITY_250ns, + MBG_EST_TIME_QUALITY_1us, + MBG_EST_TIME_QUALITY_2_5us, + MBG_EST_TIME_QUALITY_10us, + MBG_EST_TIME_QUALITY_25us, + MBG_EST_TIME_QUALITY_100us, + MBG_EST_TIME_QUALITY_250us, + MBG_EST_TIME_QUALITY_1ms, + MBG_EST_TIME_QUALITY_2_5ms, + MBG_EST_TIME_QUALITY_10ms, + MBG_EST_TIME_QUALITY_25ms, + MBG_EST_TIME_QUALITY_100ms, + MBG_EST_TIME_QUALITY_250ms, + MBG_EST_TIME_QUALITY_1s, + MBG_EST_TIME_QUALITY_10s, + MBG_EST_TIME_QUALITY_more_10s, + N_MBG_EST_TIME_QUALITYS +}; + + +#define MBG_EST_TIME_QUALITY_STRS \ +{ \ + "Unknown", \ + "Unknown", \ + "Unknown", \ + "1 ns", \ + "10 ns", \ + "25 ns", \ + "100 ns", \ + "250 ns", \ + "1 us", \ + "2.5 us", \ + "10 us", \ + "25 us", \ + "100 us", \ + "250 us", \ + "1 ms", \ + "2.5 ms", \ + "10 ms", \ + "25 ms", \ + "100 ms", \ + "250 ms", \ + "1 s", \ + "10 s", \ + "> 10 s" \ +} + + +typedef struct mbg_sys_ref_glb_status_s +{ + uint32_t master_idx; ///< Index of currently used reference source, see ::MBG_SYS_REF_SRC_INFO_IDX::idx + uint8_t ref_type; ///< Reference type of the currently used clock, see ::MULTI_REF_TYPES + uint8_t reserved_1[3]; ///< Reserved, currently always 0 + + XMR_HOLDOVER_STATUS holdover_status; ///< See ::XMR_HOLDOVER_STATUS, holdover status of currently used reference source + + uint8_t clock_idx; ///< Index of the currently used clock starting with 0, depends on #master_idx + uint8_t osc_type; ///< Oscillator type of the currently selected clock, see ::GPS_OSC_TYPES + TM_GPS_STATUS tm_gps_status; ///< Status flags from ::TM_GPS of the currently used clock, see ::TM_GPS_STATUS_BIT_MASKS + + uint8_t est_time_quality; ///< Current estimated time quality of the used clock, see ::MBG_EST_TIME_QUALITY + uint8_t reserved_2[3]; ///< Reserved, currently always 0 + uint16_t scaled_log_variance; ///< Current variance of the clock, depending on the oscillator type as defined in IEEE1588 + uint16_t reserved_3; ///< Reserved, currently always 0 + + UTC utc_parms; ///< %UTC offset, leap second information, etc., see ::UTC, + ///< TODO!!! can this be used? contains doubles + + uint32_t reserved_4[8]; ///< Reserved, currently always 0 + +} MBG_SYS_REF_GLB_STATUS; + + +#define _mbg_swab_sys_ref_glb_status( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->master_idx ); \ + _mbg_swab_xmr_holdover_status( &(_p)->holdover_status ); \ + _mbg_swab_tm_gps_status( &(_p)->tm_gps_status ); \ + _mbg_swab32( &(_p)->est_time_quality ); \ + _mbg_swab16( &(_p)->scaled_log_variance ); \ + _mbg_swab_utc_parm( &(_p)->utc_parms ); \ +} while ( 0 ) + + +enum MBG_SYS_REF_SRC_STATUS_SUPP_FLAGS +{ + SYS_REF_SRC_STATUS_SUPP_SSM, ///< Indicates, that ::MBG_SYS_REF_SRC_STATUS::ssm holds a valid value + SYS_REF_SRC_STATUS_SUPP_OUTAGE_CNT, ///< Indicates, that ::MBG_SYS_REF_SRC_STATUS::outage_cnt holds a valid value + SYS_REF_SRC_STATUS_SUPP_XMR_HOLDOVER, ///< Indicates, that ::MBG_SYS_REF_SRC_STATUS::xmr_holdover holds valid values + SYS_REF_SRC_STATUS_SUPP_XMR_STATS, ///< Indicates, that ::MBG_SYS_REF_SRC_STATUS::xmr_stats holds valid values + SYS_REF_SRC_STATUS_SUPP_XMR_METRICS, ///< Indicates, that ::MBG_SYS_REF_SRC_STATUS::xmr_metrics holds valid values + N_SYS_REF_SRC_STATUS_SUPP_FLAGS +}; + + +enum MBG_SYS_REF_SRC_STATUS_SUPP_MASKS +{ + SYS_REF_SRC_STATUS_SUPP_SSM_MASK = ( 1UL << SYS_REF_SRC_STATUS_SUPP_SSM ), ///< See ::SYS_REF_SRC_STATUS_SUPP_SSM + SYS_REF_SRC_STATUS_SUPP_OUTAGE_CNT_MASK = ( 1UL << SYS_REF_SRC_STATUS_SUPP_OUTAGE_CNT ), ///< See ::SYS_REF_SRC_STATUS_SUPP_OUTAGE_CNT + SYS_REF_SRC_STATUS_SUPP_XMR_HOLDOVER_MASK = ( 1UL << SYS_REF_SRC_STATUS_SUPP_XMR_HOLDOVER ), ///< See ::SYS_REF_SRC_STATUS_SUPP_XMR_HOLDOVER + SYS_REF_SRC_STATUS_SUPP_XMR_STATS_MASK = ( 1UL << SYS_REF_SRC_STATUS_SUPP_XMR_STATS ), ///< See ::SYS_REF_SRC_STATUS_SUPP_XMR_STATS + SYS_REF_SRC_STATUS_SUPP_XMR_METRICS_MASK = ( 1UL << SYS_REF_SRC_STATUS_SUPP_XMR_METRICS ) ///< See ::SYS_REF_SRC_STATUS_SUPP_XMR_METRICS +}; + + +typedef struct mbg_sys_ref_src_status_s +{ + char str[SYS_REF_SRC_INFO_STR_LEN]; ///< String for reference identification + + uint32_t xmr_status; ///< See @ref XMR_REF_STATUS_BIT_MASKS + + NANO_TIME offset; ///< time offset from main time base + + uint8_t ssm; ///< synchronization status message, only valid if ::SYS_REF_SRC_STATUS_SUPP_SSM_MASK is set + uint8_t prio; ///< Priority for this reference + uint8_t reserved[2]; ///< Reserved, currently always 0 + + uint32_t outage_cnt; ///< signal outage counter, incremented on loss of signal, only valid if ::SYS_REF_SRC_STATUS_SUPP_OUTAGE_CNT_MASK is set + + XMR_HOLDOVER_STATUS xmr_holdover; ///< See ::XMR_HOLDOVER_STATUS, only valid if ::SYS_REF_SRC_STATUS_SUPP_XMR_HOLDOVER_MASK is set + XMR_STATS xmr_stats; ///< See ::XMR_STATS, only valid if ::SYS_REF_SRC_STATUS_SUPP_XMR_STATS_MASK is set + XMR_METRICS xmr_metrics; ///< See ::XMR_METRICS, only valid if ::SYS_REF_SRC_STATUS_SUPP_XMR_METRICS_MASK is set + + uint32_t supp_flags; ///< See ::MBG_SYS_REF_SRC_STATUS_SUPP_MASKS + + uint32_t reserved_4[8]; ///< Reserved, currently always 0 + +} MBG_SYS_REF_SRC_STATUS; + + +#define _mbg_swab_sys_ref_src_status( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->xmr_status ); \ + _mbg_swab_nano_time( &(_p)->offset ); \ + _mbg_swab32( &(_p)->outage_cnt ); \ + _mbg_swab_xmr_holdover_status( &(_p)->xmr_holdover ); \ + _mbg_swab_xmr_stats( &(_p)->xmr_stats ); \ + _mbg_swab_xmr_metrics( &(_p)->xmr_metrics ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SYS_REF_SRC_STATUS status; + +} MBG_SYS_REF_SRC_STATUS_IDX; + + +#define _mbg_swab_sys_ref_src_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_sys_ref_src_status( &(_p)->status ); \ +} while ( 0 ) + + +/** @} defgroup group_sys_ref */ + + +/** + * @defgroup group_led_api Meinberg LED API definitions + * + * @note These structures and definitions are only supported by a device + * if ::MBG_XFEATURE_LED_API is set in the extended device features. + * + * @{ */ + + +/** + * @brief General LED info to be read from a device + * + * Used to query from a device how many LEDs are supported + * by the device, then index 0..::MBG_LED_LIMITS::num_leds-1 + * ::MBG_LED_INFO_IDX or ::MBG_LED_SETTINGS_IDX structures + * can be read from or written to the device. + * + * @see ::MBG_LED_SETTINGS_IDX + * @see ::MBG_LED_INFO_IDX + */ +typedef struct +{ + uint8_t num_leds; ///< Number of supported LEDs, see ::MBG_LED_SETTINGS_IDX::idx and ::MBG_LED_INFO_IDX::idx + uint8_t reserved_0; ///< Currently reserved, unused, always 0 + uint16_t reserved_1; ///< Currently reserved, unused, always 0 + uint32_t reserved_2; ///< Currently reserved, unused, always 0 + +} MBG_LED_LIMITS; + +#define _mbg_swab_mbg_led_limits( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->num_leds ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +/** + * @brief Possible modes of LEDs + * + * Used with ::MBG_LED_SETTINGS::mode + * + * @see ::MBG_LED_MODE_MASKS + */ +enum MBG_LED_MODES +{ + MBG_LED_MODE_OFF, + MBG_LED_MODE_ON, + MBG_LED_MODE_FLASH, + MBG_LED_MODE_FLASH_5S, + N_MBG_LED_MODES +}; + + + +/** + * @brief Bit masks associated with LED modes + * + * Used with ::MBG_LED_INFO::supp_modes + * + * @see ::MBG_LED_MODES + */ +enum MBG_LED_MODE_MASKS +{ + MBG_LED_MODE_MASK_OFF = ( 1UL << MBG_LED_MODE_OFF ), ///< See ::MBG_LED_MODE_OFF + MBG_LED_MODE_MASK_ON = ( 1UL << MBG_LED_MODE_ON ), ///< See ::MBG_LED_MODE_ON + MBG_LED_MODE_MASK_FLASH = ( 1UL << MBG_LED_MODE_FLASH ), ///< See ::MBG_LED_MODE_FLASH + MBG_LED_MODE_MASK_FLASH_5S = ( 1UL << MBG_LED_MODE_FLASH_5S ) ///< See ::MBG_LED_MODE_FLASH_5S +}; + + +/** + * @brief Names of LED modes + * + * Can be used to initialize a string array of ::N_MBG_LED_MODES entries, + * so the number of strings must correspond to ::N_MBG_LED_MODES. + * + * @see ::MBG_LED_MODES + * @see ::MBG_LED_MODE_MASKS + */ +#define MBG_LED_MODE_STRS \ +{ \ + "Off", \ + "On", \ + "Flash", \ + "Flash 5s" \ +} + + + +/** + * @brief Possible colors of LEDs + * + * Used with ::MBG_LED_SETTINGS::color + * + * @see ::MBG_LED_COLOR_MASKS + */ +enum MBG_LED_COLORS +{ + MBG_LED_COLOR_GREEN, + MBG_LED_COLOR_RED, + MBG_LED_COLOR_YELLOW, + MBG_LED_COLOR_BLUE, + N_MBG_LED_COLORS +}; + + + +/** + * @brief Bit masks of possible LED colors + * + * Used with ::MBG_LED_INFO::supp_colors + * + * @see ::MBG_LED_COLORS + */ +enum MBG_LED_COLOR_MASKS +{ + MBG_LED_COLOR_MASK_GREEN = ( 1UL << MBG_LED_COLOR_GREEN ), ///< See ::MBG_LED_COLOR_GREEN + MBG_LED_COLOR_MASK_RED = ( 1UL << MBG_LED_COLOR_RED ), ///< See ::MBG_LED_COLOR_RED + MBG_LED_COLOR_MASK_YELLOW = ( 1UL << MBG_LED_COLOR_YELLOW ), ///< See ::MBG_LED_COLOR_YELLOW + MBG_LED_COLOR_MASK_BLUE = ( 1UL << MBG_LED_COLOR_BLUE ) ///< See ::MBG_LED_COLOR_BLUE +}; + + + +/** + * @brief Names of LED colors + * + * Can be used to initialize a string array of ::N_MBG_LED_COLORS entries, + * so the number of strings must correspond to ::N_MBG_LED_COLORS. + * + * @see ::MBG_LED_COLORS + * @see ::MBG_LED_COLOR_MASKS + */ +#define MBG_LED_COLOR_STRS \ +{ \ + "Green", \ + "Red", \ + "Yellow", \ + "Blue" \ +} + + + +/** + * @brief Configuration settings for a single LED + * + * @see ::MBG_LED_SETTINGS_IDX + */ +typedef struct +{ + uint8_t mode; ///< LED mode, see ::MBG_LED_MODES + uint8_t color; ///< LED color, see ::MBG_LED_COLORS + uint16_t reserved; ///< Currently reserved, unused, always 0 + +} MBG_LED_SETTINGS; + +#define _mbg_swab_mbg_led_settings( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->mode ); \ + _mbg_swab8( &(_p)->color ); \ + _mbg_swab16( &(_p)->reserved ); \ +} while ( 0 ) + + + +/** + * @brief Configuration settings for a single LED, plus index + * + * @see ::MBG_LED_SETTINGS + * @see ::MBG_LED_LIMITS + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0..::MBG_LED_LIMITS::num_leds-1. + MBG_LED_SETTINGS settings; ///< LED settings. + +} MBG_LED_SETTINGS_IDX; + +#define _mbg_swab_mbg_led_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_mbg_led_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Current settings and general capabilities of an LED + * + * This structure should be read from the device to retrieve the + * current settings of an LED plus its capabilities, e.g. the + * supported modes, colors, etc. + * + * @see ::MBG_LED_INFO_IDX + */ +typedef struct +{ + MBG_LED_SETTINGS settings; ///< Current LED settings + uint32_t supp_modes; ///< Supported modes, see ::MBG_LED_MODE_MASKS + uint32_t supp_colors; ///< Supported colors, see ::MBG_LED_COLOR_MASKS + uint32_t reserved; ///< Currently reserved, unused, always 0 + uint32_t flags; ///< Currently reserved, unused, always 0 + +} MBG_LED_INFO; + +#define _mbg_swab_mbg_led_info( _p ) \ +do \ +{ \ + _mbg_swab_mbg_led_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_modes ); \ + _mbg_swab32( &(_p)->supp_colors ); \ + _mbg_swab32( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Current settings and general capabilities of an LED, plus index + * + * @see ::MBG_LED_INFO + * @see ::MBG_LED_LIMITS + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0..::MBG_LED_LIMITS::num_leds-1. + MBG_LED_INFO info; ///< LED info. + +} MBG_LED_INFO_IDX; + +#define _mbg_swab_mbg_led_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_mbg_led_info( &(_p)->info ); \ +} while ( 0 ) + +/** @} defgroup group_led_api */ + + + +/** + * @defgroup group_lne_api Definitions specific to LNE devices + * + * @note These structures and definitions are only supported by a device + * if ::MBG_XFEATURE_LNE_API is set in the extended device features. + * + * @{ */ + + +/** + * @brief General info to be read from an LNE device + * + * Used to query from a device e.g. how many LNE ports are provided + * by the device, then index 0..::MBG_LNE_LIMITS::num_ports-1 + * ::MBG_LNE_PORT_INFO_IDX or ::MBG_LNE_PORT_SETTINGS_IDX structures + * can be read from or written to the device. + * + * @see ::MBG_LNE_PORT_SETTINGS_IDX + * @see ::MBG_LNE_PORT_INFO_IDX + */ +typedef struct +{ + uint8_t num_ports; ///< Number of supported ports, see ::MBG_LNE_PORT_SETTINGS_IDX::idx and ::MBG_LNE_PORT_INFO_IDX::idx + uint8_t reserved_0; ///< Currently reserved, unused, always 0 + uint16_t reserved_1; ///< Currently reserved, unused, always 0 + uint32_t features; // ### TODO Mask of supported features, see ::MBG_LNE_FEAT_MASKS + ///< Currently reserved, unused, always 0 + uint32_t reserved_2; ///< Currently reserved, unused, always 0 + +} MBG_LNE_LIMITS; + +#define _mbg_swab_mbg_lne_limits( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->num_ports ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->features ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ +} while ( 0 ) + + + +#if 0 //### TODO //################# + +/** + * @brief LNE feature bits + * + * Used to define ::MBG_LNE_FEAT_MASKS + * + * @see ::MBG_LNE_FEAT_MASKS + */ +enum MBG_LNE_FEAT_BITS +{ + MBG_LNE_FEAT_BIT_SWITCH_PWR, ///< Power switching off all LNE ports at once supported, see ::MBG_LNE_PWR_STATE + N_MBG_LNE_FEAT_BITS +}; + + + +/** + * @brief LNE feature bit masks + * + * Used with ::MBG_LNE_LIMITS::features + * + * @see ::MBG_LNE_FEAT_BITS + */ +enum MBG_LNE_FEAT_MASKS +{ + MBG_LNE_FEAT_MASK_SWITCH_PWR = ( 1UL << MBG_LNE_FEAT_BIT_SWITCH_PWR ) ///< See ::MBG_LNE_FEAT_BIT_SWITCH_PWR +}; + +#endif + + + +/** + * @brief Configuration settings for a single LNE port + * + * @see ::MBG_LNE_PORT_SETTINGS_IDX + */ +typedef struct +{ + uint32_t reserved_0; ///< currently reserved, unused, always 0 + uint32_t reserved_1; ///< currently reserved, unused, always 0 + uint32_t reserved_2; ///< currently reserved, unused, always 0 + uint32_t flags; ///< currently reserved, unused, always 0 + +} MBG_LNE_PORT_SETTINGS; + +#define _mbg_swab_mbg_lne_port_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Configuration settings for a single LNE port, plus index + * + * @see ::MBG_LNE_PORT_SETTINGS + * @see ::MBG_LNE_LIMITS + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0..::MBG_LNE_LIMITS::num_ports-1. + MBG_LNE_PORT_SETTINGS settings; ///< LNE settings. + +} MBG_LNE_PORT_SETTINGS_IDX; + +#define _mbg_swab_mbg_lne_port_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_mbg_lne_port_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +/** + * @brief Current settings and general capabilities of an LNE port + * + * This structure should be read from the device to retrieve the + * current settings of an LNE port plus its capabilities, ### e.g. the + * supported modes, colors, etc. + * + * @see ::MBG_LNE_PORT_INFO_IDX + */ +typedef struct +{ + MBG_LNE_PORT_SETTINGS settings; ///< Current LNE port settings + MBG_MAC_ADDR mac_addr; ///< The MAC address assigned to this port + uint32_t reserved_0; ///< currently reserved, unused, always 0 + uint32_t reserved_1; ///< currently reserved, unused, always 0 + uint32_t reserved_2; ///< currently reserved, unused, always 0 + uint32_t flags; ///< See ::LNE_PORT_FLAG_MASKS + +} MBG_LNE_PORT_INFO; + +#define _mbg_swab_mbg_lne_port_info( _p ) \ +do \ +{ \ + _mbg_swab_mbg_lne_port_settings( &(_p)->settings ); \ + _mbg_swab_mbg_mac_addr( &(_p)->mac_addr ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Current settings and general capabilities of an LNE port, plus index + * + * @see ::MBG_LNE_PORT_INFO + * @see ::MBG_LNE_LIMITS + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0..::MBG_LED_LIMITS::num_leds-1. + MBG_LNE_PORT_INFO info; ///< LNE port info. + +} MBG_LNE_PORT_INFO_IDX; + +#define _mbg_swab_mbg_lne_port_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_mbg_lne_port_info( &(_p)->info ); \ +} while ( 0 ) + + + +/** + * @brief LNE port flag bits + * + * Used to define ::LNE_PORT_FLAG_MASKS + * + * @see ::LNE_PORT_FLAG_MASKS + */ +enum LNE_PORT_FLAG_BITS +{ + LNE_PORT_FLAG_BIT_IS_SFP, + N_LNE_PORT_FLAG_BITS +}; + + + +/** + * @brief LNE port flag bit masks + * + * Used with ::MBG_LNE_PORT_INFO::flags + * + * @see ::LNE_PORT_FLAG_BITS + */ +enum LNE_PORT_FLAG_MASKS +{ + LNE_PORT_FLAG_MASK_IS_SFP = ( 1UL << LNE_PORT_FLAG_BIT_IS_SFP ) ///< See ::LNE_PORT_FLAG_BIT_IS_SFP +}; + + +/** @} defgroup group_lne_api */ + + + +/** + * @defgroup group_pwr_ctl_api Definitions for power control API + * + * @note These structures and definitions are only supported by a device + * if ::MBG_XFEATURE_PWR_CTL_API is set in the extended device features. + * + * @{ */ + + +/** + * @brief Device power states + * + * Used with ::MBG_PWR_CTL::state. + */ +enum MBG_PWR_STATES +{ + MBG_PWR_STATE_OFF, + MBG_PWR_STATE_ON, + N_MBG_PWR_STATES +}; + + + +/** + * @brief Device power control + * + * Used to change or retrieve the power state of a device. + */ +typedef struct +{ + uint8_t state; ///< See ::MBG_PWR_STATES + uint8_t reserved_0; ///< Currently reserved, unused, always 0 + uint16_t reserved_1; ///< Currently reserved, unused, always 0 + +} MBG_PWR_CTL; + +#define _mbg_swab_mbg_pwr_ctl( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->state ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ +} while ( 0 ) + +/** @} defgroup group_pwr_ctl_api */ + + + + +/** + * @defgroup group_ext_sys_info Extended system information + * + * @note This structure and its definitions are only supported by a device + * if ::MBG_XFEATURE_EXT_SYS_INFO is set in the extended device features. + * + * @{ */ + + +/** + * @brief Bits used to define ::MBG_EXT_SYS_INFO_MSKS + * + * @see ::MBG_EXT_SYS_INFO_MSKS + */ +enum MBG_EXT_SYS_INFO_BITS +{ + MBG_EXT_SYS_INFO_BIT_SW_REV, + MBG_EXT_SYS_INFO_BIT_HW_REV, + MBG_EXT_SYS_INFO_BIT_OS_REV, + MBG_EXT_SYS_INFO_BIT_FPGA_REV, + MBG_EXT_SYS_INFO_BIT_CORE_MOD_REV, + MBG_EXT_SYS_INFO_BIT_OS_TYPE, + MBG_EXT_SYS_INFO_BIT_RAM_SIZE, + MBG_EXT_SYS_INFO_BIT_STORAGE_SIZE, + MBG_EXT_SYS_INFO_BIT_RELEASE_CANDIDATE, + MBG_EXT_SYS_INFO_BIT_OS_TARGET, + MBG_EXT_SYS_INFO_BIT_STATUS, ///< Bit to announce ::MBG_EXT_SYS_STATUS support + MBG_EXT_SYS_INFO_BIT_COMMIT_HASH, + MBG_EXT_SYS_INFO_BIT_OS_NAME, + N_MBG_EXT_SYS_INFO_BITS +}; + +/** + * @brief Bit masks of supported revision numbers + * + * Used with ::MBG_EXT_SYS_INFO::supp_members + * + * @see ::MBG_EXT_SYS_INFO_BITS + */ +enum MBG_EXT_SYS_INFO_MSKS +{ + MBG_EXT_SYS_INFO_MSK_SW_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_SW_REV ), ///< See ::MBG_EXT_SYS_INFO_BIT_SW_REV + MBG_EXT_SYS_INFO_MSK_HW_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_HW_REV ), ///< See ::MBG_EXT_SYS_INFO_BIT_HW_REV + MBG_EXT_SYS_INFO_MSK_OS_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_REV ), ///< See ::MBG_EXT_SYS_INFO_BIT_OS_REV + MBG_EXT_SYS_INFO_MSK_FPGA_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_FPGA_REV ), ///< See ::MBG_EXT_SYS_INFO_BIT_FPGA_REV + MBG_EXT_SYS_INFO_MSK_CORE_MOD_REV = ( 1UL << MBG_EXT_SYS_INFO_BIT_CORE_MOD_REV ), ///< See ::MBG_EXT_SYS_INFO_BIT_CORE_MOD_REV + MBG_EXT_SYS_INFO_MSK_OS_TYPE = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_TYPE ), ///< See ::MBG_EXT_SYS_INFO_BIT_OS_TYPE + MBG_EXT_SYS_INFO_MSK_RAM_SIZE = ( 1UL << MBG_EXT_SYS_INFO_BIT_RAM_SIZE ), ///< See ::MBG_EXT_SYS_INFO_BIT_RAM_SIZE + MBG_EXT_SYS_INFO_MSK_STORAGE_SIZE = ( 1UL << MBG_EXT_SYS_INFO_BIT_STORAGE_SIZE ), ///< See ::MBG_EXT_SYS_INFO_BIT_STORAGE_SIZE + MBG_EXT_SYS_INFO_MSK_RELEASE_CANDIDATE = ( 1UL << MBG_EXT_SYS_INFO_BIT_RELEASE_CANDIDATE ), ///< See ::MBG_EXT_SYS_INFO_BIT_RELEASE_CANDIDATE + MBG_EXT_SYS_INFO_MSK_OS_TARGET = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_TARGET ), ///< See ::MBG_EXT_SYS_INFO_BIT_OS_TARGET + MBG_EXT_SYS_INFO_MSK_STATUS = ( 1UL << MBG_EXT_SYS_INFO_BIT_STATUS ), ///< See ::MBG_EXT_SYS_INFO_BIT_STATUS + MBG_EXT_SYS_INFO_MSK_COMMIT_HASH = ( 1UL << MBG_EXT_SYS_INFO_BIT_COMMIT_HASH ), ///< See ::MBG_EXT_SYS_INFO_BIT_COMMIT_HASH + MBG_EXT_SYS_INFO_MSK_OS_NAME = ( 1UL << MBG_EXT_SYS_INFO_BIT_OS_NAME ) ///< See ::MBG_EXT_SYS_INFO_BIT_OS_NAME +}; + + +enum MBG_EXT_SYS_INFO_PROC_TYPES +{ + MBG_EXT_SYS_INFO_PROC_TYPE_NONE, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_A9, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_SAM3u, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_SAM3s, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_STM32F4, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_STM32F0, + MBG_EXT_SYS_INFO_PROC_TYPE_CORTEX_STM32F7, + N_MBG_EXT_SYS_INFO_PROC_TYPES +}; + +#define MBG_EXT_SYS_INFO_PROC_STRS \ +{ \ + "None", \ + "Cortex A9", \ + "Cortex SAM3u", \ + "Cortex SAM3s", \ + "Cortex STM32F4", \ + "Cortex STM32F0", \ + "Cortex STM32F7" \ +} + +enum MBG_EXT_SYS_INFO_FPGA_TYPES +{ + MBG_EXT_SYS_INFO_FPGA_TYPE_NONE, + MBG_EXT_SYS_INFO_FPGA_TYPE_CYCLONE5_SOC, ///< System on chip + MBG_EXT_SYS_INFO_FPGA_TYPE_CYCLONE5, ///< Stand alone FPGA + MBG_EXT_SYS_INFO_FPGA_TYPE_CYCLONE4GX15, + MBG_EXT_SYS_INFO_FPGA_TYPE_CYLCONE4CE22, + N_MBG_EXT_SYS_INFO_FPGA_TYPES +}; + +#define MBG_EXT_SYS_INFO_FPGA_STRS \ +{ \ + "None", \ + "Cyclone5 SoC", \ + "Cyclone5", \ + "Cyclone4GX15", \ + "Cyclone4CE22" \ +} + +enum MBG_EXT_SYS_INFO_CORE_MOD_TYPES +{ + MBG_EXT_SYS_INFO_CORE_MOD_TYPE_NONE, + MBG_EXT_SYS_INFO_CORE_MOD_TYPE_UBX_LEA_M8F, ///< u-blox GNSS module without Galileo support + MBG_EXT_SYS_INFO_CORE_MOD_TYPE_UBX_LEA_M8T, ///< u-blox GNSS module with Galileo support + N_MBG_EXT_SYS_INFO_CORE_MOD_TYPES +}; + +#define MBG_EXT_SYS_INFO_CORE_MOD_STRS \ +{ \ + "None", \ + "u-blox LEA-M8F", \ + "u-blox LEA-M8T" \ +} + +/* + * OS Type can be used a GPS_MODEL_CODE + */ +enum MBG_EXT_SYS_INFO_OS_TYPES +{ + MBG_EXT_SYS_INFO_OS_TYPE_NONE, + MBG_EXT_SYS_INFO_OS_TYPE_PICO_OS, + MBG_EXT_SYS_INFO_OS_TYPE_NANO_OS, + MBG_EXT_SYS_INFO_OS_TYPE_MICRO_OS, + MBG_EXT_SYS_INFO_OS_TYPE_SYNC_OS, + MBG_EXT_SYS_INFO_OS_TYPE_ANY_OS, + N_MBG_EXT_SYS_INFO_OS_TYPES +}; + + +#define MBG_EXT_SYS_INFO_OS_SHORT_STRS \ +{ \ + " ", \ + "p", \ + "n", \ + "u", \ + "s", \ + "x" \ +} + + +#define MBG_EXT_SYS_INFO_OS_STRS \ +{ \ + "none", \ + "pico", \ + "nano", \ + "micro", \ + "sync", \ + "any" \ +} + +/* + * OS target information are only relevant for updates. The unique combination + * of CPU and GEN defines a specific update for this kind of hardware (FPGA) and CPU + * model. This means all microSync single boards (MSSB) do have the same + * update file as CPU and hardware (FPGA) are always equal. + * Several variants (power, telecom, etc...) do effect the real board layout + * (connectors, etc..) but never the update file as long as CPU and GEN are + * equal. The variant member only is informational. + */ + +/// CPU mainline +#define MBG_EXT_SYS_INFO_CPU_MSK 0xff + +/// CPU generation +#define MBG_EXT_SYS_INFO_CPU_GEN_MSK 0xf + +/// CPU variant +#define MBG_EXT_SYS_INFO_CPU_VAR_MSK 0xf + +#define _mbg_ext_sys_info_get_cpu(var) (((var) >> 8) & MBG_EXT_SYS_INFO_CPU_MSK) +#define _mbg_ext_sys_info_get_cpu_gen(var) (((var) >> 4) & MBG_EXT_SYS_INFO_CPU_GEN_MSK) +#define _mbg_ext_sys_info_get_cpu_var(var) ((var) & MBG_EXT_SYS_INFO_CPU_VAR_MSK) + +enum MBG_EXT_SYS_INFO_CPUS +{ + MBG_EXT_SYS_INFO_CPU_UNKNOWN, + MBG_EXT_SYS_INFO_CPU_HPS_USB_HOST, + MBG_EXT_SYS_INFO_CPU_HPS_USB_DEVICE, + MBG_EXT_SYS_INFO_CPU_MSSB_USB_HOST, + N_MBG_EXT_SYS_INFO_CPUS +}; + +#define MBG_EXT_SYS_INFO_CPU_STRS \ +{ \ + "Unknown", \ + "HPS USB host", \ + "HPS USB device", \ + "microSync SB USB host" \ +} + +#define __CPU_CODEC(cpu, gen, var) \ + (((cpu) & MBG_EXT_SYS_INFO_CPU_MSK) << 8) | \ + (((gen) & MBG_EXT_SYS_INFO_CPU_GEN_MSK) << 4) | \ + ((var) & MBG_EXT_SYS_INFO_CPU_VAR_MSK) + + +/** + * @defgroup group_os_target_codes OS target codes + * + * Status word, associated bit numbers and bit masks indicating + * whether certain data from the GPS satellites are + * available and valid. + * + * These bits defined are set in ::BVAR_STAT if the corresponding + * parameters are NOT valid and complete. + * + * @see ::MBG_EXT_SYS_INFO_CPUS + * @see ::MBG_OS_TARGET_CODE + * + * @{ */ + +/// - CPU 1 : HPS USB host +/// - Gen 1 : HPS100 +/// - Var 0 : Base (4 x LED, USB to serial, 2 x SMA, SFP, RJ-45) +/// - Product(s) : microSync HSXXX +#define HPS_USB_HOST_G1_V0 __CPU_CODEC(MBG_EXT_SYS_INFO_CPU_HPS_USB_HOST, 1, 0) + +/// - CPU 2 : HPS USB device +/// - Gen 1 : HPS100 +/// - Var 0 : Base (4 x LED, USB to serial, 2 x SMA, SFP, RJ-45) +/// - Product(s) : HPS100 +#define HPS_USB_DEVICE_G1_V0 __CPU_CODEC(MBG_EXT_SYS_INFO_CPU_HPS_USB_DEVICE, 1, 0) + +/// - CPU 2 : HPS USB device +/// - Gen 1 : HPS100 +/// - Var 1 : USB lock (4 x LED, USB to serial, SMA, USB lock, SFP, RJ-45) +/// - Product(s) : SSP100 +#define HPS_USB_DEVICE_G1_V1 __CPU_CODEC(MBG_EXT_SYS_INFO_CPU_HPS_USB_DEVICE, 1, 1) + +/// - CPU 3 : microSync SB USB host +/// - Gen 1 : MSSB100 +/// - Var 0 : Base (10 MHz in, PPS in, 10 MHz sine out, 10 MHz out, +/// 4 x LED, RS232, USB to serial, USB, 4 x SFP, 2 x DFK PPO, +/// 2 x Optocoupler) +/// - Product(s) : microSyncHR, microSyncRX +#define MSSB_USB_HOST_G1_V0 __CPU_CODEC(MBG_EXT_SYS_INFO_CPU_MSSB_USB_HOST, 1, 0) + +/** @} defgroup group_os_target_codes */ + + + +/** + * @brief Meinberg OS release year offset. + * + * If ::MBG_EXT_SYS_INFO_MSK_OS_TYPE is set in ::MBG_EXT_SYS_INFO::supp_members + * then ::MBG_OS_YEAR_CONSTANT needs to be added to the major version code of ::MBG_EXT_SYS_INFO::sw_rev + * to get the meinbergOS release year (4 digits), and its minor version represents the release month (2 digits). + */ +#define MBG_OS_YEAR_CONSTANT 2000 + + +/** + * @brief Bit-coded CPU type information. + * + * - Bits 0..3: CPU Type + * - Bits 4..7: CPU generation + * - Bits 8..15: CPU variant (currently unused) + * + * @see @ref group_os_target_codes + */ +typedef uint16_t MBG_OS_TARGET_CODE; + + +typedef struct mbg_ext_sys_info_s +{ + uint32_t supp_members; ///< ::MBG_EXT_SYS_INFO_MSKS + + uint32_t sw_rev; + uint32_t hw_rev; + uint32_t os_rev; + uint32_t fpga_rev; + + uint16_t proc_type; ///< See ::MBG_EXT_SYS_INFO_PROC_TYPES + uint16_t fpga_type; ///< See ::MBG_EXT_SYS_INFO_FPGA_TYPES + uint16_t core_mod_type; ///< See ::MBG_EXT_SYS_INFO_CORE_MOD_TYPES + uint16_t mbg_os_type; ///< See ::MBG_EXT_SYS_INFO_OS_TYPES + + uint32_t core_mod_rev; + + uint32_t ram_size; ///< RAM size in MB + uint32_t storage_size; ///< Storage size in MB + + uint8_t release_candidate;///< Release candidate number (0 = final release) + + /// Reserved for future use, currently 0. + uint8_t reserved_rev_3[3]; + + MBG_OS_TARGET_CODE os_target; ///< See @ref group_os_target_codes + + uint16_t reserved_rev_4; + uint32_t commit_hash; + char os_name[16]; + +} MBG_EXT_SYS_INFO; + +#define _mbg_swab_ext_sys_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab32( &(_p)->sw_rev ); \ + _mbg_swab32( &(_p)->hw_rev ); \ + _mbg_swab32( &(_p)->os_rev ); \ + _mbg_swab32( &(_p)->fpga_rev ); \ + _mbg_swab16( &(_p)->proc_type ); \ + _mbg_swab16( &(_p)->fpga_type ); \ + _mbg_swab16( &(_p)->core_mod_type ); \ + _mbg_swab16( &(_p)->os_type ); \ + _mbg_swab16( &(_p)->reserved ); \ + _mbg_swab32( &(_p)->core_mod_rev ); \ + _mbg_swab32( &(_p)->ram_size ); \ + _mbg_swab32( &(_p)->storage_size ); \ + _mbg_swab16( &(_p)->os_target ); \ +} while ( 0 ) + + +#define _mbg_encode_revision( _major, _minor, _patch ) \ + ( ( (_major) << 24) | ( (_minor) << 16 ) | (_patch) ) + + +#define _mbg_decode_revision( _rev, _major, _minor, _patch ) \ +{ \ + (_major) = ( (_rev) >> 24 ) & 0xff; \ + (_minor) = ( (_rev) >> 16 ) & 0xff; \ + (_patch) = (_rev) & 0xffff; \ +} + + +#define MBG_REVISION_RC_DEVEL ((uint8_t)(-1)) +#define MBG_REVISION_RC_DEVEL_STR "devel" + + +/** + * @brief Bits used to define ::MBG_EXT_SYS_STATUS_MSKS + * + * @see ::MBG_EXT_SYS_STATUS_MSKS + */ +enum MBG_EXT_SYS_STATUS_BITS +{ + MBG_EXT_SYS_STATUS_BIT_UPTIME, + MBG_EXT_SYS_STATUS_BIT_FREE_RAM, + MBG_EXT_SYS_STATUS_BIT_LOAD, + MBG_EXT_SYS_STATUS_BIT_FLAGS, + N_MBG_EXT_SYS_STATUS_BITS +}; + +/** + * @brief Bit masks of supported status values in ::MBG_EXT_SYS_STATUS + * + * Used with ::MBG_EXT_SYS_STATUS::supp_members + * + * @see ::MBG_EXT_SYS_STATUS_BITS + */ +enum MBG_EXT_SYS_STATUS_MSKS +{ + MBG_EXT_SYS_STATUS_MSK_UPTIME = ( 1UL << MBG_EXT_SYS_STATUS_BIT_UPTIME ), ///< See ::MBG_EXT_SYS_STATUS_BIT_UPTIME + MBG_EXT_SYS_STATUS_MSK_FREE_RAM = ( 1UL << MBG_EXT_SYS_STATUS_BIT_FREE_RAM ), ///< See ::MBG_EXT_SYS_STATUS_BIT_FREE_RAM + MBG_EXT_SYS_STATUS_MSK_LOAD = ( 1UL << MBG_EXT_SYS_STATUS_BIT_LOAD ), ///< See ::MBG_EXT_SYS_STATUS_BIT_LOAD + MBG_EXT_SYS_STATUS_MSK_FLAGS = ( 1UL << MBG_EXT_SYS_STATUS_BIT_FLAGS ) ///< See ::MBG_EXT_SYS_STATUS_BIT_FLAGS +}; + +/** + * @brief Bits used to define ::MBG_EXT_SYS_STATUS_FLAGS_MSKS + * + * @see ::MBG_EXT_SYS_STATUS_FLAGS_MSKS + */ + +enum MBG_EXT_SYS_STATUS_FLAGS_BITS +{ + MBG_EXT_SYS_STATUS_FLAG_BIT_CONFIG_CHANGED, ///< Indicates if runtime config is different to startup config + N_MBG_EXT_SYS_STATUS_FLAGS_BITS +}; + +/** + * @brief Bit masks of supported status flags in ::MBG_EXT_SYS_STATUS + * + * Used with ::MBG_EXT_SYS_STATUS::supp_flags + * + * @see ::MBG_EXT_SYS_STATUS_FLAGS_BITS + */ + +enum MBG_EXT_SYS_STATUS_FLAGS_MSKS +{ + MBG_EXT_SYS_STATUS_FLAG_MSK_CONFIG_CHANGED = ( 1UL << MBG_EXT_SYS_STATUS_FLAG_BIT_CONFIG_CHANGED ) ///< See ::MBG_EXT_SYS_STATUS_FLAG_BIT_CONFIG_CHANGED +}; + + +typedef struct mbg_ext_sys_status_s +{ + uint32_t supp_members; ///< Indicates, which members of this struct are supported, see ::MBG_EXT_SYS_STATUS_MSKS + uint32_t uptime; ///< Seconds since boot + + uint32_t free_ram; ///< Free RAM in MB + + uint16_t supp_flags; ///< Indicates, which flags are supported see ::MBG_EXT_SYS_STATUS_FLAGS_MSKS + uint16_t flags; ///< See ::MBG_EXT_SYS_STATUS_FLAGS_MSKS + + uint16_t load_1m; ///< Multiplied by 100 since original value is a double + uint16_t load_5m; ///< Multiplied by 100 since original value is a double + uint16_t load_15m; ///< Multiplied by 100 since original value is a double + uint16_t reserved_2; + + uint32_t reserved_3[10]; + +} MBG_EXT_SYS_STATUS; + +#define _mbg_swab_ext_sys_status( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab32( &(_p)->uptime ); \ + _mbg_swab32( &(_p)->free_ram ); \ + _mbg_swab16( &(_p)->load_1m ); \ + _mbg_swab16( &(_p)->load_5m ); \ + _mbg_swab16( &(_p)->load_15m ); \ +} while ( 0 ) + + + +/** @} defgroup group_ext_sys_info */ + + +/** + * @defgroup group_license_limits License information + * + * @note This is probably obsolete. + * + * @{ */ + + +#define MBG_MAX_LICENSES 32 + + +/** + * @brief General license information to be read from a device + * + * Used to query from a device how many and which different license types + * are supported. If a special type is supported (licenses[MBG_LICENSE_BASE_TYPES] > 0), its + * license specific information can be queried from 0..licenses[MBG_LICENSE_BASE_TYPES]-1 via + * its license specific [...]_IDX structures and TLV API command codes. + * See ::MBG_XFEATURE_TLV_API and ::MBG_TLV_FEAT_TYPES. + */ +typedef struct +{ + uint8_t licenses[MBG_MAX_LICENSES]; ///< To get the number of supported licenses + ///< of a specific type you need to access the array + ///< with the specififc license index defined at ::MBG_LICENSE_BASE_TYPES. +} MBG_LICENSE_LIMITS; + + +enum MBG_LICENSE_BASE_TYPES +{ + MBG_LICENSE_BASE_TYPE_PTPV2, + MBG_LICENSE_BASE_TYPE_NTP, + MBG_LICENSE_BASE_TYPE_PTPV1, + MBG_LICENSE_BASE_TYPE_TIME_MONITOR, + N_MBG_LICENSE_BASE_TYPES +}; + + +/** + * @brief Bits used to define ::MBG_LICENSE_BASE_MSKS + * + * @see ::MBG_LICENSE_BASE_MSKS + */ +enum MBG_LICENSE_BASE_FLAGS +{ + MBG_LICENSE_BASE_FLAG_SUPP_UPGRADE, ///< License supports upgrading / modifying + N_MBG_LICENSE_BASE_FLAGS +}; + + +/** + * @brief Bit masks of common supported base license flags + * + * Used with ::MBG_LICENSE_BASE::supp_flags + * + * @see ::MBG_LICENSE_BASE_FLAGS + */ +enum MBG_LICENSE_BASE_MSKS +{ + MBG_LICENSE_BASE_MSK_SUPP_UPGRADE = ( 1UL << MBG_LICENSE_BASE_FLAG_SUPP_UPGRADE ) ///< See ::MBG_LICENSE_BASE_FLAG_SUPP_UPGRADE +}; + + +/** + * @brief Common license information + * + * Should be part of each individual license type. + */ +typedef struct +{ + uint8_t type; ///< See ::MBG_LICENSE_BASE_TYPES + uint8_t reserved_1; ///< Reserved for future use, currently 0 + uint16_t reserved_2; ///< Reserved for future use, currently 0 + uint32_t supp_flags; ///< See ::MBG_LICENSE_BASE_MSKS + uint32_t reserved_3; ///< Reserved for future use, currently 0 + uint32_t reserved_4; ///< Reserved for future use, currently 0 + +} MBG_LICENSE_BASE; + +#define _mbg_swab_license_base( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +/** + * @brief Bits used to define ::MBG_LICENSE_PTPV2_MEMBER_MSKS + * + * @see ::MBG_LICENSE_PTPV2_MEMBER_MSKS + */ +enum MBG_LICENSE_PTPV2_MEMBERS +{ + MBG_LICENSE_PTPV2_MEMBER_MAX_UCLIENTS, + MBG_LICENSE_PTPV2_MEMBER_MAX_MTRANS, + N_MBG_LICENSE_PTPV2_MEMBERS +}; + + +/** + * @brief Bit masks of PTPV2 license specific members + * + * Used with ::MBG_LICENSE_PTPV2::supp_members + * + * @see ::MBG_LICENSE_PTPV2_MEMBERS + */ +enum MBG_LICENSE_PTPV2_MEMBER_MSKS +{ + MBG_LICENSE_PTPV2_MEMBER_MSK_MAX_UCLIENTS = ( 1UL << MBG_LICENSE_PTPV2_MEMBER_MAX_UCLIENTS ), ///< See ::MBG_LICENSE_PTPV2_MEMBER_MAX_UCLIENTS + MBG_LICENSE_PTPV2_MEMBER_MSK_MAX_MTRANS = ( 1UL << MBG_LICENSE_PTPV2_MEMBER_MAX_MTRANS ) ///< See ::MBG_LICENSE_PTPV2_MEMBER_MAX_MTRANS +}; + + +/** + * @brief PTPV2 specific license information + * + */ +typedef struct +{ + MBG_LICENSE_BASE base; ///< See ::MBG_LICENSE_BASE + uint32_t supp_members; ///< See ::MBG_LICENSE_PTPV2_MEMBER_MSKS + uint32_t reserved_1; ///< Reserved for future use, currently 0 + uint16_t max_uclients; ///< Maximal number of supported unicast clients. + uint16_t reserved_2; ///< Reserved for future use, currently 0 + uint32_t max_mtrans; ///< Maximal number of supported multicast transactions per second. + uint32_t reserved_3; ///< Reserved for future use, currently 0 + uint32_t reserved_4; ///< Reserved for future use, currently 0 + uint32_t reserved_5; ///< Reserved for future use, currently 0 + uint32_t reserved_6; ///< Reserved for future use, currently 0 + +} MBG_LICENSE_PTPV2; + +#define _mbg_swab_license_ptpv2( _p ) \ +do \ +{ \ + _mbg_swab_license_base( &(_p)->base ); \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab16( &(_p)->max_uclients ); \ + _mbg_swab32( &(_p)->max_mtrans ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_LICENSE_PTPV2 license; + +} MBG_LICENSE_PTPV2_IDX; + +#define _mbg_swab_license_ptpv2_idx( _p ) \ +do \ +{ \ + _mbg_swab_license_ptpv2( &(_p)->license ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + + +/** + * @brief Bits used to define ::MBG_LICENSE_NTP_MEMBER_MSKS + * + * @see ::MBG_LICENSE_NTP_MEMBER_MSKS + */ +enum MBG_LICENSE_NTP_MEMBERS +{ + MBG_LICENSE_NTP_MEMBER_MAX_RPS, + N_MBG_LICENSE_NTP_MEMBERS +}; + + +/** + * @brief Bit masks of NTP license specific members + * + * Used with ::MBG_LICENSE_NTP::supp_members + * + * @see ::MBG_LICENSE_PTPV2_MEMBERS + */ +enum MBG_LICENSE_NTP_MEMBER_MSKS +{ + MBG_LICENSE_NTP_MEMBER_MSK_MAX_RPS = ( 1UL << MBG_LICENSE_NTP_MEMBER_MAX_RPS ) ///< See ::MBG_LICENSE_NTP_MEMBER_MAX_RPS +}; + + +/** + * @brief NTP specific license information + */ +typedef struct +{ + MBG_LICENSE_BASE base; ///< See ::MBG_LICENSE_BASE + uint32_t supp_members; ///< See ::MBG_LICENSE_NTP_MEMBER_MSKS + uint32_t max_rps; ///< Maximum number of supported NTP requests per second + uint32_t reserved_1; ///< Reserved for future use, currently 0 + uint32_t reserved_2; ///< Reserved for future use, currently 0 + uint32_t reserved_3; ///< Reserved for future use, currently 0 + uint32_t reserved_4; ///< Reserved for future use, currently 0 + uint32_t reserved_5; ///< Reserved for future use, currently 0 + uint32_t reserved_6; ///< Reserved for future use, currently 0 + +} MBG_LICENSE_NTP; + +#define _mbg_swab_license_ntp( _p ) \ +do \ +{ \ + _mbg_swab_license_base( &(_p)->base ); \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab32( &(_p)->max_rps ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_LICENSE_NTP license; + +} MBG_LICENSE_NTP_IDX; + +#define _mbg_swab_license_ntp_idx( _p ) \ +do \ +{ \ + _mbg_swab_license_ntp( &(_p)->license ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + +/** + * @brief Bits used to define ::MBG_LICENSE_PTPV1_MEMBER_MSKS + * + * @see ::MBG_LICENSE_PTPV1_MEMBER_MSKS + */ +enum MBG_LICENSE_PTPV1_MEMBERS +{ + MBG_LICENSE_PTPV1_MEMBER_MAX_RPS, + N_MBG_LICENSE_PTPV1_MEMBERS +}; + + +/** + * @brief Bit masks of PTPV1 license specific members + * + * Used with ::MBG_LICENSE_PTPV1::supp_members + * + * @see ::MBG_LICENSE_PTPV2_MEMBERS + */ +enum MBG_LICENSE_PTPV1_MEMBER_MSKS +{ + MBG_LICENSE_PTPV1_MEMBER_MSK_MAX_RPS = ( 1UL << MBG_LICENSE_PTPV1_MEMBER_MAX_RPS ) ///< See ::MBG_LICENSE_PTPV1_MEMBER_MAX_RPS +}; + + +/** + * @brief NTP specific license information + */ +typedef struct +{ + MBG_LICENSE_BASE base; ///< See ::MBG_LICENSE_BASE + uint32_t supp_members; ///< See ::MBG_LICENSE_PTPV1_MEMBER_MSKS + uint32_t max_rps; ///< Maximum number of supported PTPv1 delay requests per second + uint32_t reserved_1; ///< Reserved for future use, currently 0 + uint32_t reserved_2; ///< Reserved for future use, currently 0 + uint32_t reserved_3; ///< Reserved for future use, currently 0 + uint32_t reserved_4; ///< Reserved for future use, currently 0 + uint32_t reserved_5; ///< Reserved for future use, currently 0 + uint32_t reserved_6; ///< Reserved for future use, currently 0 + +} MBG_LICENSE_PTPV1; + +#define _mbg_swab_license_ptpv1( _p ) \ +do \ +{ \ + _mbg_swab_license_base( &(_p)->base ); \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab32( &(_p)->max_rps ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_LICENSE_PTPV1 license; + +} MBG_LICENSE_PTPV1_IDX; + +#define _mbg_swab_license_ptpv1_idx( _p ) \ +do \ +{ \ + _mbg_swab_license_ptpv1( &(_p)->license ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + +/** + * @brief Bits used to define ::MBG_LICENSE_TIME_MONITOR_MEMBER_MSKS + * + * @see ::MBG_LICENSE_TIME_MONITOR_MEMBER_MSKS + */ +enum MBG_LICENSE_TIME_MONITOR_MEMBERS +{ + MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_PTPV2_CLIENTS, + MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_NTP_CLIENTS, + N_MBG_LICENSE_TIME_MONITOR_MEMBERS +}; + + +/** + * @brief Bit masks of Sync Monitor license specific members + * + * Used with ::MBG_LICENSE_TIME_MONITOR::supp_members + * + * @see ::MBG_LICENSE_TIME_MONITOR_MEMBERS + */ +enum MBG_LICENSE_TIME_MONITOR_MEMBER_MSKS +{ + MBG_LICENSE_TIME_MONITOR_MEMBER_MSK_MAX_PTPV2_CLIENTS = ( 1UL << MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_PTPV2_CLIENTS ), ///< See ::MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_PTPV2_CLIENTS + MBG_LICENSE_TIME_MONITOR_MEMBER_MSK_MAX_NTP_CLIENTS = ( 1UL << MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_NTP_CLIENTS ) ///< See ::MBG_LICENSE_TIME_MONITOR_MEMBER_MAX_NTP_CLIENTS +}; + + +/** + * @brief Sync Monitor specific license information + * + */ +typedef struct +{ + MBG_LICENSE_BASE base; ///< See ::MBG_LICENSE_BASE + uint32_t supp_members; ///< See ::MBG_LICENSE_TIME_MONITOR_MEMBER_MSKS + uint32_t reserved_1; ///< Reserved for future use, currently 0 + uint16_t max_ptpv2_clients; ///< Maximum number of supported PTPv2 clients to be monitored + uint16_t max_ntp_clients; ///< Maximum number of supported NTP clients to be monitored + uint32_t reserved_2; ///< Reserved for future use, currently 0 + uint32_t reserved_3; ///< Reserved for future use, currently 0 + uint32_t reserved_4; ///< Reserved for future use, currently 0 + uint32_t reserved_5; ///< Reserved for future use, currently 0 + uint32_t reserved_6; ///< Reserved for future use, currently 0 + +} MBG_LICENSE_TIME_MONITOR; + +#define _mbg_swab_license_time_monitor( _p ) \ +do \ +{ \ + _mbg_swab_license_base( &(_p)->base ); \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab16( &(_p)->max_ptpv2_clients ); \ + _mbg_swab16( &(_p)->max_ntp_clients ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_LICENSE_TIME_MONITOR license; + +} MBG_LICENSE_TIME_MONITOR_IDX; + +#define _mbg_swab_license_time_monitor_idx( _p ) \ +do \ +{ \ + _mbg_swab_license_time_monitor( &(_p)->license ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + +/** @} defgroup group_license_limits */ + + + +/** + * @defgroup group_clk_res_info Clock resolution info + * + * @note This structure and its definitions are only supported by a device + * if ::MBG_XFEATURE_CLK_RES_INFO is set in the extended device features. + * + * @{ */ + +/** + * @brief Clock resolution information + * + * @see @ref group_clk_res_info + */ +typedef struct +{ + uint32_t base_clk; ///< Base clock of the internal time base [MHz] + uint32_t num_clk_phase; ///< Number of multi-phase clock signals + uint32_t reserved_9; + uint32_t reserved_8; + uint32_t reserved_7; + uint32_t reserved_6; + uint32_t reserved_5; + uint32_t reserved_4; + uint32_t reserved_3; + uint32_t reserved_2; + uint32_t reserved_1; + uint32_t reserved_0; + +} MBG_CLK_RES_INFO; + +#define _mbg_swab_mbg_clk_res_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->base_clk ); \ + _mbg_swab32( &(_p)->num_clk_phase ); \ + _mbg_swab32( &(_p)->reserved_9 ); \ + _mbg_swab32( &(_p)->reserved_8 ); \ + _mbg_swab32( &(_p)->reserved_7 ); \ + _mbg_swab32( &(_p)->reserved_6 ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_0 ); \ +} while ( 0 ) + +/** @} defgroup group_clk_res_info */ + + + +/** + * @brief Type of upcoming transaction sequence + * + * Used in combination with ::GPS_BEGIN_TRANSACTION and ::GPS_END_TRANSACTION + * to announce which type of transaction is going to be started. Thus the receiver + * can prepare for following actions. + */ +enum MBG_TRANSACTION_TYPES +{ + MBG_TRANSACTION_TYPE_NONE, + /* ### TODO FIXME + * Network transaction requires at least and as first command: + * - ::GPS_NET_GLB_CFG (::MBG_NET_GLB_CFG_INFO) + * Depending on ::MBG_NET_GLB_CFG_INFO::glb_settings and its num_[...] + * members there are a couple of index commands which should be handled in any order: + * - ::GPS_NET_DNS_SRVR (::MBG_IP_ADDR_IDX) + * - ::GPS_NET_DNS_SRCH_DOM (::MBG_NET_NAME_IDX) + * - ::GPS_NET_INTF_LINK_IDX (::MBG_NET_INTF_LINK_INFO_IDX) + * - ::GPS_NET_INTF_ADDR_IDX (::MBG_NET_INTF_ADDR_INFO_IDX) + * - ::GPS_NET_INTF_ROUTE_IDX (::MBG_NET_INTF_ROUTE_INFO_IDX) + */ + MBG_TRANSACTION_TYPE_NETWORK, + MBG_TRANSACTION_TYPE_PTP, + /* + * Commands in any order if supp. by ::MBG_SNMP_GLB_INFO::max_[...] + * and ::MBG_SNMP_GLB_INFO::supp_versions + * + * Should be used within ::MBG_TRANSACTION_TYPE_MONITORING but may also be + * used stand-alone. + * + * - ::GPS_SNMP_GLB_SETTINGS + * - ::GPS_SNMP_V12_SETTINGS_IDX + * - ::GPS_SNMP_V12_TRAP_SETTINGS_IDX + * - ::GPS_SNMP_V3_SETTINGS_IDX + * - ::GPS_SNMP_V3_TRAP_SETTINGS_IDX + */ + MBG_TRANSACTION_TYPE_MONITORING_SNMP, + /* + * NTP transaction requires at least and as first command: + * ::GPS_NTP_GLB_CFG + * Commands in any order if supp. by ::MBG_NTP_GLB_INFO + * and ::MBG_SNMP_GLB_INFO::supp_versions + * + * - ::GPS_NTP_REFCLK_CFG + * - ::GPS_NTP_MISC_LIMITS + * - ::GPS_NTP_MISC_ORPHAN_MODE + * - ::GPS_NTP_SYMM_KEY_LIMITS + * - ::GPS_NTP_SYMM_KEY_CFG + * - ::GPS_NTP_TRUSTED_KEY_CFG + * - ::GPS_NTP_CLNT_MODE_CFG + * - ::GPS_NTP_SRV_MODE_CFG + * - ::GPS_NTP_PEER_SETTINGS_IDX + * - ::GPS_NTP_SYS_STATE + * - ::GPS_NTP_PEER_STATE_IDX + */ + MBG_TRANSACTION_TYPE_NTP, + /* + * IO Port transaction used to read or write ALL_IO_PORT_INFO + * Commands related to this transaction: + * + * - ::GPS_IO_PORT_LIMITS + * - ::GPS_IO_PORT_SETTINGS_IDX + * - ::GPS_IO_PORT_INFO_IDX + * - ::GPS_IO_PORT_TYPE_INFO_IDX + * - ::GPS_IO_PORT_STATUS_IDX + */ + MBG_TRANSACTION_TYPE_IO_PORT, + /* + * Commands in any order if ::MBG_XFEATURE_MONITORING is set in + * ::MBG_XFEATURE_BUFFER. + * + * Transactions ::MBG_TRANSACTION_TYPE_MONITORING_SNMP and + * ::MBG_TRANSACTION_TYPE_EVENTS may also be opened within + * ::MBG_TRANSACTION_TYPE_MONITORING transaction. + * + * - ::GPS_MONITORING_LIMITS + * - ::GPS_MONITORING_STATUS + */ + MBG_TRANSACTION_TYPE_MONITORING, + /* + * Commands in any order if ::MBG_XFEATURE_MONITORING is set in + * ::MBG_XFEATURE_BUFFER. + * + * Should be used within ::MBG_TRANSACTION_TYPE_MONITORING but may also be + * used stand-alone. + * + * - ::GPS_EVENT_IDX + * - ::GPS_EVENT_STAT_IDX + */ + MBG_TRANSACTION_TYPE_EVENTS, + + /* + * User Management transaction is supported, + * if ::MBG_XFEATURE_MONITORING is set in ::MBG_XFEATURE_BUFFER and + * requires at least and as first command: ::GPS_USER_MNGMNT_INFO + * + * Other commands in any order + * + * - ::GPS_USER_INFO_IDX + * - ::GPS_USER_LEVEL_INFO_IDX + * - ::GPS_USER_STATUS_IDX + */ + MBG_TRANSACTION_TYPE_USER_MNGMNT, + + /* + * Should be used within ::MBG_TRANSACTION_TYPE_MONITORING but may also be + * used stand-alone. + * + * - ::GPS_SYSLOG_GLB_INFO + * - ::GPS_SYSLOG_INFO_IDX + */ + MBG_TRANSACTION_TYPE_MONITORING_SYSLOG, + + /* + * Firmware Management transaction is supported, + * if ::MBG_XFEATURE_FW_MNGMNT is set in ::MBG_XFEATURE_BUFFER and + * requires at least and as first command: ::GPS_FW_GLB_INFO + * + * Other commands in any order + * + * - ::GPS_FW_INFO_IDX + * - ::GPS_FW_UFU_INFO_IDX + */ + MBG_TRANSACTION_TYPE_FIRMWARE_MNGMNT, + + /* + * Database transaction is supported, + * if ::MBG_XFEATURE_DATABASE is set in ::MBG_XFEATURE_BUFFER and + * requires at least and as first command: ::GPS_DATABASE_GLB_INFO + * + * Other commands in any order + * + * - ::GPS_DATABASE_GLB_INFO + * - ::GPS_DATABASE_INFO_IDX + */ + MBG_TRANSACTION_TYPE_DATABASE, + + /* + * PTP next gen transaction is supported, + * if ::MBG_XFEATURE_PTP_NG is set in ::MBG_XFEATURE_BUFFER and + * (if used in a save function) requires at least and as first command: + * ::GPS_PTP_NG_GLB_INFO + * + * Other commands in any order + * + * - ::GPS_PTP_NG_GLB_INFO + * - ::GPS_PTP_NG_TSTAMPER_INFO_IDX + * - ::GPS_PTP_NG_INSTC_INFO_IDX + * - ::GPS_PTP_NG_INSTC_STATUS_IDX + * - ::GPS_PTP_NG_UC_MASTER_INFO_IDX + * - ::GPS_PTP_NG_UC_SLAVE_STATUS_IDX + */ + MBG_TRANSACTION_TYPE_PTP_NG, + + /* + * Sys ref API is supported, if ::MBG_XFEATURE_SYS_REF is set + * in ::MBG_XFEATURE_BUFFER and supports the following commands: + * + * - ::GPS_SYS_REF_LIMITS + * - ::GPS_SYS_REF_GLB_STATUS + * - ::GPS_SYS_REF_SRC_INFO_IDX + * - ::GPS_SYS_REF_SRC_STATUS_IDX + */ + MBG_TRANSACTION_TYPE_SYS_REF, + + MAX_MBG_TRANSACTION_TYPES +}; + + +#define MBG_TRANSACTION_MSK_SET 0x8000 ///< Only relevant when starting a transaction +#define MBG_TRANSACTION_MSK_SUCCESS 0x4000 ///< Only relevant when ending a transaction + +#define _mbg_is_set_transaction( _type ) ( ( _type ) & MBG_TRANSACTION_MSK_SET ) +#define _mbg_transaction_type_set( _type ) ( ( _type ) |= MBG_TRANSACTION_MSK_SET ) + +#define _mbg_transaction_success( _type ) ( ( _type ) & MBG_TRANSACTION_MSK_SUCCESS ) +#define _mbg_transaction_set_success( _type ) ( ( _type ) |= MBG_TRANSACTION_MSK_SUCCESS ) + + +/** + * @defgroup group_io_ports IO Port API + * + * @note This structure and its definitions are only supported by a device + * if ::MBG_XFEATURE_IO_PORTS is set in the extended device features. + * + * @{ */ + +/** + * @brief IO Port types + * + * Used with ::MBG_IO_PORT_TYPE_INFO::port_type and ::MBG_IO_PORT_SETTINGS::port_type + */ +enum MBG_IO_PORT_TYPES +{ + MBG_IO_PORT_TYPE_PPS, + MBG_IO_PORT_TYPE_10MHz, + MBG_IO_PORT_TYPE_2048KHz, + MBG_IO_PORT_TYPE_GPIO, + MBG_IO_PORT_TYPE_ETHERNET, + MBG_IO_PORT_TYPE_TERMINAL, + MBG_IO_PORT_TYPE_MULTI, + MBG_IO_PORT_TYPE_POUT, + MBG_IO_PORT_TYPE_SWITCH, + MBG_IO_PORT_TYPE_TIMECODE, ///< e.g. IRIG AM/DC, see ::MBG_IO_PORT_SHAPE_LEVELS + MBG_IO_PORT_TYPE_LIGHT, + MBG_IO_PORT_TYPE_ANTENNA, + MBG_IO_PORT_TYPE_UART, + MBG_IO_PORT_TYPE_DCF77, + MBG_IO_PORT_TYPE_POWER, + MBG_IO_PORT_TYPE_SPST_RELAY, ///< Single-Pole Single-Throw Relay, two terminals which can be connected or disconnected + MBG_IO_PORT_TYPE_SPDT_RELAY, ///< Single-Pole Double-Throw Relay, common terminal connects to either of two others, never connecting to both at the same time + MBG_IO_PORT_TYPE_SYNTHESIZER, + N_MBG_IO_PORT_TYPES +}; + +/** + * @brief Port type to be used for an undefined/unassigned port + * + * Only use this for ::MBG_IO_PORT_SETTINGS::port_type + * if ::MBG_IO_PORT_SETTINGS::op_mode is ::MBG_IO_PORT_OP_MODE_NONE + */ +#define MBG_IO_PORT_TYPE_NONE ( (uint16_t) -1 ) + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_TYPES + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_TYPES entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_TYPES. + * + * @see ::MBG_IO_PORT_TYPES + */ +#define MBG_IO_PORT_TYPE_STRS \ +{ \ + "PPS", \ + "10 MHz", \ + "2048 KHz", \ + "GPIO", \ + "Ethernet", \ + "Terminal", \ + "Multi", \ + "Prog. Output", \ + "Switch", \ + "Timecode", \ + "Light", \ + "Antenna", \ + "UART", \ + "DCF77", \ + "Power", \ + "SPST Relay", \ + "SPDT Relay", \ + "Synthesizer" \ +} + + +/** + * @brief Port directions (input or output) + * + * @see ::MBG_IO_PORT_DIR_MSKS + */ +enum MBG_IO_PORT_DIRS +{ + MBG_IO_PORT_DIR_NONE = -1, ///< Only use this for ::MBG_IO_PORT_SETTINGS::direction if ::MBG_IO_PORT_SETTINGS::op_mode is ::MBG_IO_PORT_OP_MODE_NONE + MBG_IO_PORT_DIR_IN, ///< Port is input like PPS In + MBG_IO_PORT_DIR_OUT, ///< Port is output like 10Mhz + MBG_IO_PORT_DIR_IN_OUT, ///< Port can be in- & output in parallel like network port + N_MBG_IO_PORT_DIRS +}; + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_DIRS + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_DIRS entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_DIRS. + * + * @see ::MBG_IO_PORT_DIRS + */ +#define MBG_IO_PORT_DIR_STRS \ +{ \ + "Input", \ + "Output", \ + "Input/Output" \ +} + + +/** + * @brief Bit masks of Meinberg I/O port directions + * + * Used with ::MBG_IO_PORT_TYPE_INFO::supp_dirs + * + * @see ::MBG_IO_PORT_DIRS + */ +enum MBG_IO_PORT_DIR_MSKS +{ + MBG_IO_PORT_MSK_DIR_IN = ( 1UL << MBG_IO_PORT_DIR_IN ), ///< See ::MBG_IO_PORT_DIR_IN + MBG_IO_PORT_MSK_DIR_OUT = ( 1UL << MBG_IO_PORT_DIR_OUT ), ///< See ::MBG_IO_PORT_DIR_OUT + MBG_IO_PORT_MSK_DIR_IN_OUT = ( 1UL << MBG_IO_PORT_DIR_IN_OUT ) ///< See ::MBG_IO_PORT_DIR_IN_OUT +}; + + +/** + * @brief Port type sources + * + * Configurable sources for an I/O port type + * + * @see ::MBG_IO_PORT_SRC_MSKS + */ +enum MBG_IO_PORT_SRCS +{ + MBG_IO_PORT_SRC_NONE = -1, ///< Only use this for ::MBG_IO_PORT_SETTINGS::source if ::MBG_IO_PORT_SETTINGS::op_mode is ::MBG_IO_PORT_OP_MODE_NONE + MBG_IO_PORT_SRC_STATIC, ///< Static, not configurable + MBG_IO_PORT_SRC_LOCAL, ///< Locally generated, e.g. on (carrier) board + MBG_IO_PORT_SRC_ASSOC_CLOCK, ///< Fixed (wired) clock from back plane (e.g. refclock 1 in M500 IMS) + MBG_IO_PORT_SRC_ACTIVE_CLOCK, ///< Switched clock from back plane (e.g. selected by RSC) + MBG_IO_PORT_SRC_CLK1, ///< Clock 1 fixed (CPU board only) + MBG_IO_PORT_SRC_CLK2, ///< Clock 2 fixed (CPU board only) + MBG_IO_PORT_SRC_ARC, ///< Any rate converter + MBG_IO_PORT_SRC_OSC, ///< Oscillator + MBG_IO_PORT_SRC_SYNCE, ///< SyncE + MBG_IO_PORT_SRC_SWITCH_CARD, ///< Switch Card Unit fixed (SCU, RSC, ...) + MBG_IO_PORT_SRC_CONFIGURABLE, ///< configurable + MBG_IO_PORT_SRC_EXTERNAL, ///< external (e.g. for inputs) + N_MBG_IO_PORT_SRCS +}; + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_SRCS + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_SRCS entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_SRCS. + * + * @see ::MBG_IO_PORT_SRCS + */ +#define MBG_IO_PORT_SRC_STRS \ +{ \ + "Static", \ + "Locally generated", \ + "Associated clock", \ + "Active clock", \ + "Clock 1 fixed", \ + "Clock 2 fixed", \ + "Any rate converter", \ + "Oscillator", \ + "SyncE", \ + "Switch card", \ + "Configurable", \ + "External" \ +} + + +/** + * @brief Bit masks of Meinberg I/O port attitudes + * + * Used with ::MBG_IO_PORT_TYPE_INFO::supp_srcs + * + * @see ::MBG_IO_PORT_SRCS + */ +enum MBG_IO_PORT_SRC_MSKS +{ + MBG_IO_PORT_SRC_MSK_STATIC = (1UL << MBG_IO_PORT_SRC_STATIC), ///< See ::MBG_IO_PORT_SRC_STATIC + MBG_IO_PORT_SRC_MSK_LOCAL = (1UL << MBG_IO_PORT_SRC_LOCAL), ///< See ::MBG_IO_PORT_SRC_LOCAL + MBG_IO_PORT_SRC_MSK_ASSOC_CLOCK = (1UL << MBG_IO_PORT_SRC_ASSOC_CLOCK), ///< See ::MBG_IO_PORT_SRC_ASSOC_CLOCK + MBG_IO_PORT_SRC_MSK_ACTIVE_CLOCK = (1UL << MBG_IO_PORT_SRC_ACTIVE_CLOCK), ///< See ::MBG_IO_PORT_SRC_ACTIVE_CLOCK + MBG_IO_PORT_SRC_MSK_CLK1 = (1UL << MBG_IO_PORT_SRC_CLK1), ///< See ::MBG_IO_PORT_SRC_CLK1 + MBG_IO_PORT_SRC_MSK_CLK2 = (1UL << MBG_IO_PORT_SRC_CLK2), ///< See ::MBG_IO_PORT_SRC_CLK2 + MBG_IO_PORT_SRC_MSK_ARC = (1UL << MBG_IO_PORT_SRC_ARC), ///< See ::MBG_IO_PORT_SRC_ARC + MBG_IO_PORT_SRC_MSK_OSC = (1UL << MBG_IO_PORT_SRC_OSC), ///< See ::MBG_IO_PORT_SRC_OSC + MBG_IO_PORT_SRC_MSK_SYNCE = (1UL << MBG_IO_PORT_SRC_SYNCE), ///< See ::MBG_IO_PORT_SRC_SYNCE + MBG_IO_PORT_SRC_MSK_SWITCH_CARD = (1UL << MBG_IO_PORT_SRC_SWITCH_CARD), ///< See ::MBG_IO_PORT_SRC_SWITCH_CARD + MBG_IO_PORT_SRC_MSK_CONFIGURABLE = (1UL << MBG_IO_PORT_SRC_CONFIGURABLE), ///< See ::MBG_IO_PORT_SRC_CONFIGURABLE + MBG_IO_PORT_SRC_MSK_EXTERNAL = (1UL << MBG_IO_PORT_SRC_EXTERNAL) ///< See ::MBG_IO_PORT_SRC_EXTERNAL +}; + + +/** + * @brief Port connector types + * + * Used with ::MBG_IO_PORT_INFO::conn_type + * + */ +enum MBG_IO_PORT_CONN_TYPES +{ + MBG_IO_PORT_CONN_TYPE_SMA, + MBG_IO_PORT_CONN_TYPE_BNC, + MBG_IO_PORT_CONN_TYPE_DSUB25, + MBG_IO_PORT_CONN_TYPE_RJ45, + MBG_IO_PORT_CONN_TYPE_SFP, + MBG_IO_PORT_CONN_TYPE_USB_MICRO_B, + MBG_IO_PORT_CONN_TYPE_USB_A, + MBG_IO_PORT_CONN_TYPE_USB_B, + MBG_IO_PORT_CONN_TYPE_SMA_ANT, + MBG_IO_PORT_CONN_TYPE_RJ45_ETH, + MBG_IO_PORT_CONN_TYPE_2_PIN_DFK, + MBG_IO_PORT_CONN_TYPE_3_PIN_DFK, + MBG_IO_PORT_CONN_TYPE_16_PIN_DFK, + MBG_IO_PORT_CONN_TYPE_BNC_ISO, + MBG_IO_PORT_CONN_TYPE_DSUB9, + MBG_IO_PORT_CONN_TYPE_FIBRE_ST, + MBG_IO_PORT_CONN_TYPE_XHE_SPI, + MBG_IO_PORT_CONN_TYPE_LED_BUTTON, + MBG_IO_PORT_CONN_TYPE_QUAD_LED, + MBG_IO_PORT_CONN_TYPE_5_PIN_DFK, + MBG_IO_PORT_CONN_TYPE_SINGLE_LED, + N_MBG_IO_PORT_CONN_TYPES +}; + + +/** + * @brief Number of variable pols of the connector type, see ::MBG_IO_PORT_INFO::pols + * + * Used with ::MBG_IO_PORT_INFO::conn_type and ::MBG_IO_PORT_INFO::pols + * + */ +#define MBG_IO_PORT_CONN_TYPE_VAR_POLS \ +{ \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 16, \ + 1, \ + 1, \ + 1, \ + 1, \ + 1, \ + 4, \ + 1, \ + 1 \ +} + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_CONN_TYPES + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_CONN_TYPES entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_CONN_TYPES. + * + * @see ::MBG_IO_PORT_CONN_TYPES + */ +#define MBG_IO_PORT_CONN_TYPE_STRS \ +{ \ + "SMA", \ + "BNC", \ + "D-Sub 25", \ + "RJ45", \ + "SFP", \ + "USB Micro B", \ + "USB A", \ + "USB B", \ + "SMA Antenna", \ + "RJ45 Ethernet", \ + "DFK 2-Pin", \ + "DFK 3-Pin", \ + "DFK 16-Pin", \ + "BNC isolated", \ + "D-Sub 9", \ + "Fibre ST", \ + "XHE SPI", \ + "LED Button", \ + "Quad LED", \ + "DFK 5-Pin", \ + "Single LED" \ +} + + +enum MBG_IO_PORT_FLAGS +{ + MBG_IO_PORT_FLAG_HORIZONTAL_LAYOUT, ///< Modules (rows and columns) are layouted horizontally + MBG_IO_PORT_FLAG_FRONT_PORTS, ///< Device has ports at the front side + MBG_IO_PORT_FLAG_REAR_PORTS, ///< Device has ports at the rear side + MBG_IO_PORT_FLAG_NO_LABEL, ///< Device does not have a label + MBG_IO_PORT_FLAG_NO_GRASP, ///< Device does not have a grasp + N_MBG_IO_PORT_FLAGS +}; + + +enum MBG_IO_PORT_MSKS +{ + MBG_IO_PORT_MSK_HORIZONTAL_LAYOUT = ( 1UL << MBG_IO_PORT_FLAG_HORIZONTAL_LAYOUT ), ///< See ::MBG_IO_PORT_FLAG_HORIZONTAL_LAYOUT + MBG_IO_PORT_MSK_FRONT_PORTS = ( 1UL << MBG_IO_PORT_FLAG_FRONT_PORTS ), ///< See ::MBG_IO_PORT_FLAG_FRONT_PORTS + MBG_IO_PORT_MSK_REAR_PORTS = ( 1UL << MBG_IO_PORT_FLAG_REAR_PORTS ), ///< See ::MBG_IO_PORT_FLAG_REAR_PORTS + MBG_IO_PORT_MSK_NO_LABEL = ( 1UL << MBG_IO_PORT_FLAG_NO_LABEL ), ///< See ::MBG_IO_PORT_FLAG_REAR_PORTS + MBG_IO_PORT_MSK_NO_GRASP = ( 1UL << MBG_IO_PORT_FLAG_NO_GRASP ) ///< See ::MBG_IO_PORT_FLAG_NO_GRASP +}; + + +enum MBG_IO_PORT_BG_COLOURS +{ + MBG_IO_PORT_BG_COLOUR_SILVER, + MBG_IO_PORT_BG_COLOUR_BLACK, + MBG_IO_PORT_BG_COLOUR_BLUE, + N_MBG_IO_PORT_BG_COLOURS +}; + + +#define MBG_IO_PORT_BG_COLOUR_STRS \ +{ \ + "Silver", \ + "Black", \ + "Blue" \ +} + + +/** + * @brief Enumeration of known signal shapes/levels + * + * Used to specify the signal shape/level of an I/O port. + * + * @see ::MBG_IO_PORT_SHAPE_LEVEL_STRS + */ +enum MBG_IO_PORT_SHAPE_LEVELS +{ + MBG_IO_PORT_SHAPE_LEVEL_NONE, ///< Unknown or unspecified signal shape. + ///< Must be zero for backward compatibility. + MBG_IO_PORT_SHAPE_LEVEL_SINE, ///< Sine wave + MBG_IO_PORT_SHAPE_LEVEL_SQUARE, ///< Square wave + N_MBG_IO_PORT_SHAPE_LEVELS ///< Number of known signal shapes +}; + + +/** + * @brief String initializers for I/O port shapes/levels + * + * @see ::MBG_IO_PORT_SHAPE_LEVELS + */ +#define MBG_IO_PORT_SHAPE_LEVEL_STRS \ +{ \ + "None", \ + "Sine wave", \ + "Rectangle Pulse" \ +} + + +/** + * @brief IO Port Limits + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef struct +{ + uint8_t num_ports; + uint8_t num_cols; ///< Number of port columns this device supports + uint8_t num_rows; ///< Number of port rows this device supports + uint8_t bg_colour; ///< Background colour of the IO ports, see ::MBG_IO_PORT_BG_COLOURS + + uint32_t reserved; ///< Reserved, currently 0 + uint32_t flags; ///< See ::MBG_IO_PORT_MSKS + + uint8_t label_col; ///< Column position of the device label, consider ::MBG_IO_PORT_MSK_NO_LABEL + uint8_t label_row; ///< Row position of the device label, consider ::MBG_IO_PORT_MSK_NO_LABEL + uint8_t grasp_col; ///< Column position of the device grasp, consider ::MBG_IO_PORT_MSK_NO_GRASP + uint8_t grasp_row; ///< Row position of the device grasp, consider ::MBG_IO_PORT_MSK_NO_GRASP + + uint8_t label_rear; ///< Indicates, that the label is on the rear side + uint8_t grasp_rear; ///< Indicates, that the grasp is on the rear side + uint16_t reserved_2; ///< Reserved, currently 0 + + uint32_t reserved_3[7]; ///< Reserved, currently 0 + +} MBG_IO_PORT_LIMITS; + +#define _mbg_swab_io_port_limits( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + + +/** + * @brief Port Operation Bits + * + * Used with ::MBG_IO_PORT_SETTINGS::op_mode + * + * For now, there is a per port operation mode setting which + * is quite equal to ::ENABLE_FLAGS. + * + * @see ::MBG_IO_PORT_OP_MODE_MSKS + */ +enum MBG_IO_PORT_OP_MODE_BITS +{ + MBG_IO_PORT_OP_MODE_NONE = -1, ///< Current mode cannot be determined + MBG_IO_PORT_OP_MODE_DISABLED, ///< Disabled port + MBG_IO_PORT_OP_MODE_ALWAYS, ///< Always enable port + MBG_IO_PORT_OP_MODE_IF_SYNC_ONLY, ///< Enable port if sync only + MBG_IO_PORT_OP_MODE_AFTER_SYNC, ///< Always enable port after being sync once + MBG_IO_PORT_OP_MODE_ENABLED, ///< Enabled + MBG_IO_PORT_OP_MODE_PASSTHROUGH, ///< Forwarded signals from backplane (e.g. PPS of BPE) + N_MBG_IO_PORT_OP_MODE_BITS +}; + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_OP_MODE_BITS + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_OP_MODE_BITS entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_OP_MODE_BITS. + * + * @see ::MBG_IO_PORT_OP_MODE_BITS + */ +#define MBG_IO_PORT_OP_MODE_STRS \ +{ \ + "Disabled", \ + "Always enabled", \ + "If sync only", \ + "Always after sync", \ + "Enabled", \ + "Passed through" \ +} + + + +/** + * @brief Masks for ::MBG_IO_PORT_OP_MODE_BITS + * + * Used with ::MBG_IO_PORT_INFO::supp_op_modes + * + * @see ::MBG_IO_PORT_OP_MODE_BITS + */ +enum MBG_IO_PORT_OP_MODE_MSKS +{ + MBG_IO_PORT_OP_MODE_MSK_DISABLED = (1UL << MBG_IO_PORT_OP_MODE_DISABLED), ///< See ::MBG_IO_PORT_OP_MODE_DISABLED + MBG_IO_PORT_OP_MODE_MSK_ALWAYS = (1UL << MBG_IO_PORT_OP_MODE_ALWAYS), ///< See ::MBG_IO_PORT_OP_MODE_ALWAYS + MBG_IO_PORT_OP_MODE_MSK_IF_SYNC_ONLY = (1UL << MBG_IO_PORT_OP_MODE_IF_SYNC_ONLY), ///< See ::MBG_IO_PORT_OP_MODE_IF_SYNC_ONLY + MBG_IO_PORT_OP_MODE_MSK_AFTER_SYNC = (1UL << MBG_IO_PORT_OP_MODE_AFTER_SYNC), ///< See ::MBG_IO_PORT_OP_MODE_AFTER_SYNC + MBG_IO_PORT_OP_MODE_MSK_ENABLED = (1UL << MBG_IO_PORT_OP_MODE_ENABLED), ///< See ::MBG_IO_PORT_OP_MODE_ENABLED + MBG_IO_PORT_OP_MODE_MSK_PASSTHROUGH = (1UL << MBG_IO_PORT_OP_MODE_PASSTHROUGH) ///< See ::MBG_IO_PORT_OP_MODE_PASSTHROUGH +}; + + +/** + * @brief Physical or logical group role bits + * + * Used with ::MBG_IO_PORT_STATUS::phys_grp_role, ::MBG_IO_PORT_STATUS::log_grp_role + * + * @see ::MBG_IO_PORT_GRP_ROLE_MSKS + */ +enum MBG_IO_PORT_GRP_ROLE_BITS +{ + MBG_IO_PORT_GRP_ROLE_NONE, ///< No group role, only possible if port is not assigned to any group + MBG_IO_PORT_GRP_ROLE_MASTER, ///< Master port in group, i.e. configurable port of LIU + MBG_IO_PORT_GRP_ROLE_SLAVE, ///< Slave port in group, i.e. non-configurable port of LIU + MBG_IO_PORT_GRP_ROLE_PASSIVE, ///< Passive port in group, i.e. passive port of network group (i.e. SFP or RJ45) + N_MBG_IO_PORT_GRP_ROLE_BITS +}; + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_GRP_ROLE_BITS + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_GRP_ROLE_BITS entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_GRP_ROLE_BITS. + * + * @see ::MBG_IO_PORT_GRP_ROLE_BITS + */ +#define MBG_IO_PORT_GRP_ROLE_STRS \ +{ \ + "None", \ + "Master", \ + "Slave", \ + "Passive" \ +} + + +/** + * @brief Masks for ::MBG_IO_PORT_GRP_ROLE_BITS + * + * Used with ::MBG_IO_PORT_INFO::supp_phys_grp_roles + * + * @see ::MBG_IO_PORT_GRP_ROLE_BITS + */ +enum MBG_IO_PORT_GRP_ROLE_MSKS +{ + MBG_IO_PORT_GRP_ROLE_MSK_NONE = (1UL << MBG_IO_PORT_GRP_ROLE_NONE), ///< See ::MBG_IO_PORT_GRP_ROLE_NONE + MBG_IO_PORT_GRP_ROLE_MSK_MASTER = (1UL << MBG_IO_PORT_GRP_ROLE_MASTER), ///< See ::MBG_IO_PORT_GRP_ROLE_MASTER + MBG_IO_PORT_GRP_ROLE_MSK_SLAVE = (1UL << MBG_IO_PORT_GRP_ROLE_SLAVE), ///< See ::MBG_IO_PORT_GRP_ROLE_SLAVE + MBG_IO_PORT_GRP_ROLE_MSK_PASSIVE = (1UL << MBG_IO_PORT_GRP_ROLE_PASSIVE) ///< See ::MBG_IO_PORT_GRP_ROLE_PASSIVE +}; + + +/** + * @brief Supported members in ::MBG_IO_PORT_ANT_INFO and ::MBG_IO_PORT_ANT_SETTINGS + * + * Used with ::MBG_IO_PORT_ANT_INFO::supp_members + * + */ +enum MBG_IO_PORT_ANT_MEMBERS +{ + MBG_IO_PORT_ANT_MEMBER_GNSS, ///< Supports ::MBG_IO_PORT_ANT_INFO::gnss_info + ///< and ::MBG_IO_PORT_ANT_SETTINGS::gnss_settings. + MBG_IO_PORT_ANT_MEMBER_CAB_LEN, ///< Supports ::MBG_IO_PORT_ANT_SETTINGS::ant_cab_len. + MBG_IO_PORT_ANT_MEMBER_IGN_LOCK, ///< Supports ::MBG_IO_PORT_ANT_SETTINGS::ignore_lock. + MBG_IO_PORT_ANT_MEMBER_TR_DIST, ///< Supports ::MBG_IO_PORT_ANT_SETTINGS::tr_dist. + N_MBG_IO_PORT_ANT_MEMBERS +}; + + +enum MBG_IO_PORT_ANT_MEMBER_MSKS +{ + MBG_IO_PORT_ANT_MEMBER_MSK_GNSS = ( 1UL << MBG_IO_PORT_ANT_MEMBER_GNSS ), ///< See ::MBG_IO_PORT_ANT_MEMBER_GNSS + MBG_IO_PORT_ANT_MEMBER_MSK_CAB_LEN = ( 1UL << MBG_IO_PORT_ANT_MEMBER_CAB_LEN ), ///< See ::MBG_IO_PORT_ANT_MEMBER_CAB_LEN + MBG_IO_PORT_ANT_MEMBER_MSK_IGN_LOCK = ( 1UL << MBG_IO_PORT_ANT_MEMBER_IGN_LOCK ), ///< See ::MBG_IO_PORT_ANT_MEMBER_IGN_LOCK + MBG_IO_PORT_ANT_MEMBER_MSK_TR_DIST = ( 1UL << MBG_IO_PORT_ANT_MEMBER_TR_DIST ) ///< See ::MBG_IO_PORT_ANT_MEMBER_TR_DIST +}; + + +typedef struct +{ + uint32_t supp_members; + MBG_GNSS_MODE_INFO gnss_info; + +} MBG_IO_PORT_ANT_INFO; + +#define _mbg_swab_io_port_ant_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->supp_members ); \ + _mbg_swab_mbg_gnss_mode_info( &(_p)->gnss_info ); \ +} while ( 0 ) + +typedef struct +{ + MBG_GNSS_MODE_SETTINGS gnss_settings; + ANT_CABLE_LEN ant_cab_len; + IGNORE_LOCK ignore_lock; + /* Do not include pcpsdefs.h -> Use the non-typedefed type */ + uint16_t tr_dist; + +} MBG_IO_PORT_ANT_SETTINGS; + +#define _mbg_swab_io_port_ant_settings( _p ) \ +do \ +{ \ + _mbg_swab_mbg_gnss_mode_settings( &(_p)->gnss_settings ); \ + _mbg_swab_ant_cable_len( &(_p)->ant_cab_len ); \ + _mbg_swab16( &(_p)->ignore_lock ); \ + _mbg_swab16( &(_p)->tr_dist ); \ +} while ( 0 ) + + +typedef struct +{ + IRIG_INFO irig_info; + +} MBG_IO_PORT_TIMECODE_INFO; + +#define _mbg_swab_io_port_timecode_info( _p ) \ +do \ +{ \ + _mbg_swab_irig_info( &(_p)->irig_info ); \ +} while ( 0 ) + +typedef struct +{ + IRIG_SETTINGS irig_settings; + MBG_REF_OFFS ref_offs; ///< Fix %UTC offset of incoming IRIG codde, only for inputs. + +} MBG_IO_PORT_TIMECODE_SETTINGS; + +#define _mbg_swab_io_port_timecode_settings( _p ) \ +do \ +{ \ + _mbg_swab_irig_settings( &(_p)->irig_settings ); \ + _mbg_swab_mbg_ref_offs( &(_p)->ref_offs ); \ +} while ( 0 ) + + +/** + * @brief IO Port Settings Union + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef union +{ + MBG_GPIO_SETTINGS gpio_settings; + POUT_SETTINGS pout_settings; + MBG_IO_PORT_TIMECODE_SETTINGS timecode_settings; + MBG_IO_PORT_ANT_SETTINGS ant_settings; + PORT_SETTINGS uart_settings; + SYNTH synth_settings; + +} MBG_IO_PORT_SETTINGS_U; + +#define _mbg_swab_io_port_settings_u( _type, _p, _recv ) \ +do \ +{ \ + switch ( (_type) ) \ + { \ + case MBG_IO_PORT_TYPE_GPIO: \ + _mbg_swab_mbg_gpio_settings( &(_p)->gpio_settings, (_recv) ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_POUT: \ + if ( _recv ) \ + _mbg_swab_pout_settings_on_get( &(_p)->pout_settings ); \ + else _mbg_swab_pout_settings_on_set( &(_p)->pout_settings ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_TIMECODE: \ + _mbg_swab_io_port_timecode_settings( &(_p)->timecode_settings ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_ANTENNA: \ + _mbg_swab_io_port_ant_settings( &(_p)->ant_settings ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_UART: \ + _mbg_swab_port_settings( &(_p)->uart_settings ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_SYNTHESIZER: \ + _mbg_swab_synth( &(_p)->synth_settings ); \ + break; \ + \ + default: break; \ + } \ +} while ( 0 ) + + +#define MBG_IO_PORT_SETTINGS_MIN_SIZE 32 + + +/** + * @brief IO Port Settings + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef struct +{ + uint16_t port_type; ///< ::MBG_IO_PORT_TYPES + uint8_t direction; ///< ::MBG_IO_PORT_DIRS + uint8_t source; ///< ::MBG_IO_PORT_SRCS + uint8_t op_mode; ///< ::MBG_IO_PORT_OP_MODE_BITS + uint8_t pt_idx; ///< index of the port types (e.g. 0 for PPO0, 1 for PPO1, ...) + uint8_t reserved_1[2]; ///< Future use and padding, currently 0 + uint32_t reserved_2[6]; ///< Future use and padding, currently 0 + + /* + * Struct members above represent minimum amount of data to be sent. + * See ::MBG_IO_PORT_SETTINGS_MIN_SIZE + */ + + MBG_IO_PORT_SETTINGS_U data; ///< Data union for settings' type + +} MBG_IO_PORT_SETTINGS; + +#define _mbg_swab_io_port_settings( _p, _recv ) \ +do \ +{ \ + uint16_t t = (_p)->port_type; \ + if ( (_recv) ) \ + _mbg_swab16( &t ); \ + _mbg_swab16( &(_p)->port_type ); \ + _mbg_swab_io_port_settings_u( t, &(_p)->data, (_recv) ); \ +} while ( 0 ) + + + + +/** + * @brief IO Port Settings Index + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + * + * Indexes from 0..::MBG_IO_PORT_LIMITS::num_ports - 1 are used + * to set ::MBG_IO_PORT_SETTINGS wrapped in ::MBG_IO_PORT_SETTINGS_IDX. + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_IO_PORT_SETTINGS settings; + +} MBG_IO_PORT_SETTINGS_IDX; + +#define _mbg_swab_io_port_settings_idx( _p, _recv ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_io_port_settings( &(_p)->settings, (_recv) ); \ +} while ( 0 ) + + +#define MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE (MBG_IO_PORT_SETTINGS_MIN_SIZE + sizeof( uint32_t )) + + +#define MBG_IO_PORT_SETTINGS_IDX_SIZES \ +{ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_PPS */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_10MHz */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_2048KHz */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( MBG_GPIO_SETTINGS ), /* MBG_IO_PORT_TYPE_GPIO */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_ETHERNET */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_TERMINAL */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_MULTI */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( POUT_SETTINGS ), /* MBG_IO_PORT_TYPE_POUT */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SWITCH */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_TIMECODE_SETTINGS ), /* MBG_IO_PORT_TYPE_TIMECODE */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_LIGHT */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_ANT_SETTINGS ), /* MBG_IO_PORT_TYPE_ANTENNA */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( PORT_SETTINGS ), /* MBG_IO_PORT_TYPE_UART */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_DCF77 */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_POWER */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPST_RELAY */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPDT_RELAY */ \ + MBG_IO_PORT_SETTINGS_IDX_MIN_SIZE + sizeof( SYNTH ) /* MBG_IO_PORT_TYPE_SYNTHESIZER */ \ +} + + +enum MBG_IO_PORT_INFO_BITS +{ + MBG_IO_PORT_INFO_BIT_IS_ALIGNED, ///< Indicates, that this port shall be optically aligned to ::MBG_IO_PORT_INFO::align_rule_idx + MBG_IO_PORT_INFO_BIT_PASSED_THROUGH_CFG_NOT_SUPP ///< Indicates, that the output signal of this port (defined in (::MBG_IO_PORT_SETTINGS::data) + ///< can not be configured, if ::MBG_IO_PORT_SETTINGS::op_mode is set to ::MBG_IO_PORT_OP_MODE_PASSTHROUGH + +}; + + +enum MBG_IO_PORT_INFO_MASKS +{ + MBG_IO_PORT_INFO_MASK_IS_ALIGNED = ( 1UL << MBG_IO_PORT_INFO_BIT_IS_ALIGNED ), ///< See ::MBG_IO_PORT_INFO_BIT_IS_ALIGNED + MBG_IO_PORT_INFO_MASK_PASSED_THROUGH_CFG_NOT_SUPP = ( 1UL << MBG_IO_PORT_INFO_BIT_PASSED_THROUGH_CFG_NOT_SUPP ) ///< See ::MBG_IO_PORT_INFO_BIT_PASSED_THROUGH_CFG_NOT_SUPP + +}; + + +#define MBG_NO_PHYS_GROUP 0xFF +#define MBG_NO_LOG_GROUP 0xFF +#define MBG_IO_PORT_STR_SIZE 16 + +/** + * @brief IO Port Info + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef struct +{ + uint8_t num_types; ///< See ::MBG_IO_PORT_TYPE_INFO + uint8_t conn_type; ///< See ::MBG_IO_PORT_CONN_TYPES + uint8_t reserved_1; ///< Future use and padding, currently 0 + uint8_t align_rule_idx; ///< Index of the ::MBG_IO_PORT_INFO_IDX this port shall be optically aligned to + uint16_t supp_op_modes; ///< See ::MBG_IO_PORT_OP_MODE_MSKS + uint16_t supp_phys_grp_roles; ///< Supported roles in ::MBG_IO_PORT_STATUS::phys_grp_role, see ::MBG_IO_PORT_GRP_ROLE_MSKS + uint8_t phys_grp; ///< Physical group number (i.e. SFP/RJ45 on HPS100), or ::MBG_NO_PHYS_GROUP + uint8_t pos_col; ///< Column position of this port + uint8_t pos_row; ///< Row position of this port + uint8_t rear; ///< Indicates, whether the port is on the front or rear side + uint32_t pols; ///< Pols which are used by this IO port, only if #conn_type has more than 1 variable pol + uint32_t flags; ///< Flags, see ::MBG_IO_PORT_INFO_MASKS + uint32_t reserved_2[2]; ///< Future use and padding, currently 0 + char use_str[MBG_IO_PORT_STR_SIZE]; ///< Informational string for user interface, i.e. "NTP Status LED" + char rel_str[MBG_IO_PORT_STR_SIZE]; ///< Internally used relation string, i.e. "lan0", "fpga0" or "/dev/ttyS0" + MBG_IO_PORT_SETTINGS settings; ///< See ::MBG_IO_PORT_SETTINGS + +} MBG_IO_PORT_INFO; + +#define _mbg_port_has_phys_group( _p ) ( ( _p )->phys_grp != MBG_NO_PHYS_GROUP ) + +#define _mbg_swab_io_port_info( _p, _recv ) \ +do \ +{ \ + _mbg_swab16( &(_p)->supp_op_modes ); \ + _mbg_swab16( &(_p)->supp_phys_grp_roles ); \ + _mbg_swab32( &(_p)->pols ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab_io_port_settings( &(_p)->settings, (_recv) ); \ +} while ( 0 ) + + + +#define MBG_IO_PORT_INFO_MIN_SIZE ( 60 + MBG_IO_PORT_SETTINGS_MIN_SIZE ) + + +/** + * @brief IO Port Info Index + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_U + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + * + * Indexes from 0..::MBG_IO_PORT_LIMITS::num_ports - 1 are used + * to query ::MBG_IO_PORT_INFO wrapped in ::MBG_IO_PORT_INFO_IDX. + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_IO_PORT_INFO info; + +} MBG_IO_PORT_INFO_IDX; + +#define _mbg_swab_io_port_info_idx( _p, _recv ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_io_port_info( &(_p)->info, (_recv) ); \ +} while ( 0 ) + + + +#define MBG_IO_PORT_INFO_IDX_MIN_SIZE (MBG_IO_PORT_INFO_MIN_SIZE + sizeof( uint32_t )) + + +#define MBG_IO_PORT_INFO_IDX_SIZES \ +{ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_PPS */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_10MHz */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_2048KHz */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( MBG_GPIO_SETTINGS ), /* MBG_IO_PORT_TYPE_GPIO */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_ETHERNET */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_TERMINAL */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_MULTI */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( POUT_SETTINGS ), /* MBG_IO_PORT_TYPE_POUT */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SWITCH */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_TIMECODE_SETTINGS ), /* MBG_IO_PORT_TYPE_TIMECODE */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_LIGHT */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_ANT_SETTINGS ), /* MBG_IO_PORT_TYPE_ANTENNA */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( PORT_SETTINGS ), /* MBG_IO_PORT_TYPE_UART */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_DCF77 */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_POWER */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPST_RELAY */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPDT_RELAY */ \ + MBG_IO_PORT_INFO_IDX_MIN_SIZE + sizeof( SYNTH ) /* MBG_IO_PORT_TYPE_SYNTHESIZER */ \ +} + + +/** + * @brief IO Port Type Info Union + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef union +{ + MBG_GPIO_LIMITS gpio_limits; + POUT_INFO pout_info; + MBG_IO_PORT_TIMECODE_INFO timecode_info; + PORT_INFO uart_info; + MBG_IO_PORT_ANT_INFO ant_info; + +} MBG_IO_PORT_TYPE_INFO_U; + +#define _mbg_swab_io_port_type_info_u( _type, _p, _recv ) \ +do \ +{ \ + switch ( (_type) ) \ + { \ + case MBG_IO_PORT_TYPE_GPIO: \ + _mbg_swab_mbg_gpio_limits( &(_p)->gpio_limits, (_recv) ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_POUT: \ + _mbg_swab_pout_info_on_get( &(_p)->pout_info ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_TIMECODE: \ + _mbg_swab_io_port_timecode_info( &(_p)->timecode_info ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_ANTENNA: \ + _mbg_swab_io_port_ant_info( &(_p)->ant_info ); \ + break; \ + \ + case MBG_IO_PORT_TYPE_UART: \ + _mbg_swab_port_info( &(_p)->uart_info ); \ + break; \ + \ + default: break; \ + } \ +} while ( 0 ) + + + +#define MBG_IO_PORT_TYPE_INFO_MIN_SIZE 32 + + +/** + * @brief IO Port Type Info + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_INFO_IDX + * @see ::MBG_IO_PORT_TYPE_INFO_U + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + */ +typedef struct +{ + uint16_t port_type; ///< See ::MBG_IO_PORT_TYPES + uint16_t reserved_1; ///< Future use and padding, currently 0 + uint8_t supp_dirs; ///< See ::MBG_IO_PORT_DIR_MSKS + uint8_t pt_idx; ///< Index for this specific port type (e.g. 0 for PPO0, 1 for PPO1) + ///< especially interesting for passed through ports + uint8_t shape_level; ///< Signal shape/level, see ::MBG_IO_PORT_SHAPE_LEVELS + uint8_t reserved_2[1]; ///< Future use and padding, currently 0 + uint32_t supp_srcs; ///< See ::MBG_IO_PORT_SRC_MSKS + uint32_t reserved_3[5]; ///< Future use and padding, currently 0 + + /* + * Struct members above represent minimum amount of data to be sent. + * See ::MBG_IO_PORT_TYPE_INFO_MIN_SIZE + */ + + MBG_IO_PORT_TYPE_INFO_U data; ///< Port type specific data + +} MBG_IO_PORT_TYPE_INFO; + +#define _mbg_swab_io_port_type_info( _p, _recv ) \ +do \ +{ \ + uint16_t t = (_p)->port_type; \ + if ( (_recv) ) \ + _mbg_swab16( &t ); \ + _mbg_swab16( &(_p)->port_type ); \ + _mbg_swab_io_port_type_info_u( t, &(_p)->data, (_recv) ); \ + _mbg_swab32( &(_p)->supp_srcs ); \ +} while ( 0 ) + + +#define MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE (MBG_IO_PORT_TYPE_INFO_MIN_SIZE + 2 * sizeof( uint32_t )) + + +#define MBG_IO_PORT_TYPE_INFO_IDX_SIZES \ +{ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_PPS */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_10MHz */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_2048KHz */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( MBG_GPIO_LIMITS ), /* MBG_IO_PORT_TYPE_GPIO */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_ETHERNET */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_TERMINAL */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_MULTI */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( POUT_INFO ), /* MBG_IO_PORT_TYPE_POUT */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SWITCH */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_TIMECODE_INFO ), /* MBG_IO_PORT_TYPE_TIMECODE */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_LIGHT */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( MBG_IO_PORT_ANT_INFO ), /* MBG_IO_PORT_TYPE_ANTENNA */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE + sizeof( PORT_INFO ), /* MBG_IO_PORT_TYPE_UART */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_DCF77 */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_POWER */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPST_RELAY */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE, /* MBG_IO_PORT_TYPE_SPDT_RELAY */ \ + MBG_IO_PORT_TYPE_INFO_IDX_MIN_SIZE /* MBG_IO_PORT_TYPE_SYNTHESIZER */ \ +} + + +/** + * @brief IO Port Type Info Index + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_U + * @see ::MBG_IO_PORT_STATUS + * @see ::MBG_IO_PORT_STATUS_IDX + * + * Indexes from 0..::MBG_IO_PORT_INFO::num_types - 1 are used + * to query ::MBG_IO_PORT_TYPE_INFO wrapped in ::MBG_IO_PORT_TYPE_INFO_IDX. + * + */ +typedef struct +{ + uint32_t port_idx; + uint32_t port_type_idx; + MBG_IO_PORT_TYPE_INFO info; + +} MBG_IO_PORT_TYPE_INFO_IDX; + +#define _mbg_swab_io_port_type_info_idx( _p, _recv ) \ +do \ +{ \ + _mbg_swab32( &(_p)->port_idx ); \ + _mbg_swab32( &(_p)->port_type_idx ); \ + _mbg_swab_io_port_type_info( &(_p)->info, (_recv) ); \ +} while ( 0 ) + + + +#define MAX_IO_PORT_STATUS_BITS 64 + + +/** + * @brief Port Status Bits + * + */ +enum MBG_IO_PORT_STATUS_BITS +{ + MBG_IO_PORT_STATUS_BIT_DISABLED, ///< See ::MBG_IO_PORT_OP_MODE_DISABLED. Other bits should be 0 in this case + MBG_IO_PORT_STATUS_BIT_CARRIER_DETECTED, ///< Port has physical carrier connection (e.g. BNC cable in case of BPE) + MBG_IO_PORT_STATUS_BIT_INPUT_SIGNAL_NEVER_AVAIL, ///< Input signal has NEVER been avail + MBG_IO_PORT_STATUS_BIT_INPUT_SIGNAL_AVAIL, ///< Input signal is avail right now + MBG_IO_PORT_STATUS_BIT_INPUT_SIGNAL_LOST, ///< Input signal is currently not avail, but has been avail before + MBG_IO_PORT_STATUS_BIT_SHORT_CIRCUIT, ///< Short circuit + MBG_IO_PORT_STATUS_BIT_LIGHT_RED, ///< LED shows red light + MBG_IO_PORT_STATUS_BIT_LIGHT_GREEN, ///< LED shows green light + MBG_IO_PORT_STATUS_BIT_LIGHT_BLUE, ///< LED shows blue light + MBG_IO_PORT_STATUS_BIT_LIGHT_YELLOW, ///< LED shows yellow light + MBG_IO_PORT_STATUS_BIT_TIME_VERIFYING, ///< Received time gets verified + MBG_IO_PORT_STATUS_BIT_TELEGRAM_INCONSISTENT, ///< Received time telegram is inconsistent + N_MBG_IO_PORT_STATUS_BITS +}; + + +/** + * @brief Strings descriptions for ::MBG_IO_PORT_STATUS_BITS + * + * Can be used to initialize a string array of ::N_MBG_IO_PORT_STATUS_BITS entries, + * so the number of strings must correspond to ::N_MBG_IO_PORT_STATUS_BITS. + * + * @see ::MBG_IO_PORT_STATUS_BITS + */ +#define MBG_IO_PORT_STATUS_STRS \ +{ \ + "Disabled", \ + "Carrier detected", \ + "Input signal has never been avail", \ + "Input signal is avail", \ + "Input signal is currently lost", \ + "Short circuit", \ + "Red", \ + "Green", \ + "Blue", \ + "Yellow", \ + "Time gets verified", \ + "Telegram inconsistent" \ +} + + +/** + * @brief Array size required to store all status bits + * + * The number of bytes required to store up to ::MAX_IO_PORT_STATUS_BITS + * feature bits in a byte array. + */ +#define MAX_IO_PORT_STATUS_BYTES ( MAX_IO_PORT_STATUS_BITS / 8 ) + + +/** + * @brief A structure used to store port status bits + * + * Up to ::MAX_IO_PORT_STATUS_BITS totally can be stored, but only + * ::N_MBG_IO_PORT_STATUS_BITS are currently defined. + * + * The ::_set_io_port_status_bit macro should be used by the firmware + * to set a status bit in the buffer, and the ::check_feat_supp_byte_array + * to check if a bit is set + * + * @see ::_set_io_port_status_bit + * @see ::check_feat_supp_byte_array + */ +typedef struct mbg_io_port_status_buffer_s +{ + uint8_t b[MAX_IO_PORT_STATUS_BYTES]; + +} MBG_IO_PORT_STATUS_BUFFER; + +#define _mbg_swab_io_port_status_buffer( _p ) \ + _nop_macro_fnc() + + + +/** + * @brief Set an port status bit in a ::MBG_IO_PORT_STATUS_BUFFER + * + * Should be used by the firmware only to set one of the ::N_MBG_IO_PORT_STATUS_BITS + * in an ::MBG_IO_PORT_STATUS_BUFFER after power-up. + * + * @param[in] _status_bit One of the ::MBG_IO_PORT_STATUS_BITS + * @param[in] _status_buffp Pointer to an ::MBG_IO_PORT_STATUS_BUFFER + */ +#define _set_io_port_status_bit( _status_bit, _status_buffp ) \ + _set_array_bit( _status_bit, (_status_buffp)->b, MAX_IO_PORT_STATUS_BYTES ) + + +/** + * @brief Clear a port status bit in a ::MBG_IO_PORT_STATUS_BUFFER + * + * Should be used by the firmware only to set one of the ::N_MBG_IO_PORT_STATUS_BITS + * in an ::MBG_IO_PORT_STATUS_BUFFER after power-up. + * + * @param[in] _status_bit One of the ::MBG_IO_PORT_STATUS_BITS + * @param[in] _status_buffp Pointer to an ::MBG_IO_PORT_STATUS_BUFFER + */ +#define _clear_io_port_status_bit( _status_bit, _status_buffp ) \ + _clear_array_bit( _status_bit, (_status_buffp)->b, MAX_IO_PORT_STATUS_BYTES ) + + +/** + * @brief IO Port Status + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_U + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS_IDX + * + */ +typedef struct +{ + MBG_IO_PORT_STATUS_BUFFER supp_stati; ///< Supported ::MBG_IO_PORT_STATUS_BITS in ::MBG_IO_PORT_STATUS_BUFFER + MBG_IO_PORT_STATUS_BUFFER status; ///< See ::MBG_IO_PORT_STATUS_BUFFER + + uint8_t reserved; ///< Future use + uint8_t phys_grp_role; ///< Physical group role state, see ::MBG_IO_PORT_GRP_ROLE_BITS + uint8_t log_grp; ///< Logical group number (i.e. bond0), or ::MBG_NO_LOG_GROUP + uint8_t log_grp_role; ///< Logical group role (i.e. bond master, bond slave), see ::MBG_IO_PORT_GRP_ROLE_BITS + + uint32_t reserved_2[4]; ///< Future use, currently 0 + +} MBG_IO_PORT_STATUS; + +#define _mbg_port_has_log_group( _p ) ( ( _p )->log_grp != MBG_NO_LOG_GROUP ) + +#define _mbg_swab_io_port_status( _p ) \ +do \ +{ \ + _mbg_swab_io_port_status_buffer( &(_p)->supp_stati ); \ + _mbg_swab_io_port_status_buffer( &(_p)->status ); \ +} while ( 0 ) + + + +/** + * @brief IO Port Status + * + * @see @ref group_io_ports + * @see ::MBG_IO_PORT_SETTINGS_U + * @see ::MBG_IO_PORT_LIMITS + * @see ::MBG_IO_PORT_SETTINGS + * @see ::MBG_IO_PORT_SETTINGS_IDX + * @see ::MBG_IO_PORT_TYPE_INFO + * @see ::MBG_IO_PORT_TYPE_INFO_U + * @see ::MBG_IO_PORT_TYPE_INFO_IDX + * @see ::MBG_IO_PORT_STATUS + * + * Indexes from 0..::MBG_IO_PORT_LIMITS::num_ports - 1 are used + * to query ::MBG_IO_PORT_TYPE_INFO wrapped in ::MBG_IO_PORT_TYPE_INFO_IDX. + * + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_IO_PORT_STATUS status; + +} MBG_IO_PORT_STATUS_IDX; + +#define _mbg_swab_io_port_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_io_port_status( &(_p)->status ); \ +} while ( 0 ) + + +/** @} defgroup group_io_ports */ + + + +/** + * @defgroup group_monitoring Monitoring / notification + * + * @note This structure and its definitions are only supported by a device + * if ::MBG_XFEATURE_MONITORING is set in the extended device features. + * + * TODO: Add proper Doxygen documentation + * + * @{ */ + + +#define MBG_MONITORING_STR_SIZE 32 + +enum MBG_MONITORING_TYPES +{ + MBG_MONITORING_TYPE_SNMP, + MBG_MONITORING_TYPE_EMAIL, + MBG_MONITORING_TYPE_SYSLOG, + MBG_MONITORING_TYPE_EVENTS, + N_MBG_MONITORING_TYPES +}; + +#define MBG_MONITORING_TYPE_STRS \ +{ \ + "SNMP", \ + "Email", \ + "Syslog", \ + "Events" \ +} + +enum MBG_MONITORING_TYPE_MSKS +{ + MBG_MONITORING_TYPE_MSK_SNMP = (1UL << MBG_MONITORING_TYPE_SNMP), + MBG_MONITORING_TYPE_MSK_EMAIL = (1UL << MBG_MONITORING_TYPE_EMAIL), + MBG_MONITORING_TYPE_MSK_SYSLOG = (1UL << MBG_MONITORING_TYPE_SYSLOG), + MBG_MONITORING_TYPE_MSK_EVENTS = (1UL << MBG_MONITORING_TYPE_EVENTS) +}; + + + +typedef struct +{ + uint16_t supp_types; ///< See ::MBG_MONITORING_TYPE_MSKS + uint16_t reserved_1; + uint32_t reserved_2[3]; + +} MBG_MONITORING_LIMITS; + +#define _mbg_swab_monitoring_limits( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->supp_types ); \ +} while ( 0 ) + + + +/* If ::MBG_MONITORING_TYPE_MSK_SNMP is set in ::MBG_MONITORING_LIMITS::supp_types */ + +enum MBG_SNMP_VERSIONS +{ + MBG_SNMP_VERSION_V1, + MBG_SNMP_VERSION_V2c, + MBG_SNMP_VERSION_V3, + N_MBG_SNMP_VERSIONS +}; + +#define MBG_SNMP_VERSION_STRS \ +{ \ + "Version 1", \ + "Version 2c", \ + "Version 3" \ +} + +enum MBG_SNMP_VERSION_MSKS +{ + MBG_SNMP_VERSION_MSK_V1 = (1UL << MBG_SNMP_VERSION_V1), + MBG_SNMP_VERSION_MSK_V2c = (1UL << MBG_SNMP_VERSION_V2c), + MBG_SNMP_VERSION_MSK_V3 = (1UL << MBG_SNMP_VERSION_V3) +}; + + +enum MBG_SNMP_FLAGS +{ + MBG_SNMP_SYSTEM_USER, + MBG_SNMP_ADD_CONF, ///< Supports additional SNMP configuration (i.e. via script) + MBG_SNMP_READ_ONLY, ///< Read/Write is not supported, SNMP can be used for monitoring, only + N_MBG_SNMP_FLAGS +}; + + +#define MBG_SNMP_FLAG_STRS \ +{ \ + "System user", \ + "Additional config", \ + "Read-Only" \ +} + + +enum MBG_SNMP_FLAG_MSKS +{ + MBG_SNMP_SYSTEM_USER_MSK = ( 1UL << MBG_SNMP_SYSTEM_USER ), + MBG_SNMP_ADD_CONF_MSK = ( 1UL << MBG_SNMP_ADD_CONF ), ///< See ::MBG_SNMP_ADD_CONF + MBG_SNMP_READ_ONLY_MSK = ( 1UL << MBG_SNMP_READ_ONLY ) ///< See ::MBG_SNMP_READ_ONLY +}; + + +#define SNMP_DEF_ADD_CONF_PATH "/etc/mbg" +#define SNMP_DEF_ADD_CONF_FILENAME "snmp.conf.add" +#define SNMP_DEF_ADD_CONF_FILE SNMP_DEF_ADD_CONF_PATH "/" SNMP_DEF_ADD_CONF_FILENAME + + + +typedef struct +{ + uint8_t num_v12_settings; ///< Number of configured v1/v2 settings, see ::MBG_SNMP_V12_INFO_IDX + uint8_t num_v3_settings; ///< Number of configured v1/v2 trap receivers, see ::MBG_SNMP_V12_TRAP_INFO_IDX + uint8_t num_v12_trap_receivers; ///< Number of configured v3 settings, see ::MBG_SNMP_V3_INFO_IDX + uint8_t num_v3_trap_receivers; ///< Number of configured v3 trap receivers, see ::MBG_SNMP_V3_TRAP_INFO_IDX + uint16_t listening_port; ///< snmpd listening port, 161 by default + uint16_t reserved_1; + uint32_t reserved_2[3]; + char location[MBG_MONITORING_STR_SIZE]; + char contact[MBG_MONITORING_STR_SIZE]; + char name[MBG_MONITORING_STR_SIZE]; + char description[MBG_MONITORING_STR_SIZE]; + char reserved_3[MBG_MONITORING_STR_SIZE]; ///< Future use + char reserved_4[MBG_MONITORING_STR_SIZE]; ///< Future use + +} MBG_SNMP_GLB_SETTINGS; + +#define _mbg_swab_snmp_glb_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->listening_port ); \ +} while ( 0 ) + + + +typedef struct mbg_snmp_glb_info_s +{ + MBG_SNMP_GLB_SETTINGS settings; + uint8_t supp_versions; ///< See ::MBG_SNMP_VERSION_MSKS + uint8_t max_v12_settings; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V1 or ::MBG_SNMP_VERSION_MSK_V2c + uint8_t max_v3_settings; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V3 + uint8_t max_v12_trap_receivers; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V1 or ::MBG_SNMP_VERSION_MSK_V2c + uint8_t max_v3_trap_receivers; ///< Only valid if ::MBG_SNMP_GLB_INFO::supp_versions contains ::MBG_SNMP_VERSION_MSK_V3 + uint8_t reserved_1[1]; + uint16_t supp_flags; ///< See ::MBG_SNMP_FLAG_MSKS. ::MBG_SNMP_SYSTEM_USER_MSK is only relevant for SNMPv3. + uint32_t reserved_2[2]; + +} MBG_SNMP_GLB_INFO; + +#define _mbg_swab_snmp_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_snmp_glb_settings( &(_p)->settings ); \ + _mbg_swab16( &(_p)->supp_flags ); \ +} while ( 0 ) + + + +enum MBG_SNMP_ACCESS_TYPES +{ + MBG_SNMP_ACCESS_TYPE_RO, + MBG_SNMP_ACCESS_TYPE_RW, + N_MBG_SNMP_ACCESS_TYPES +}; + + +#define MBG_SNMP_ACCESS_TYPE_STRS \ +{ \ + "Read-only", \ + "Read-write" \ +} + + + +typedef struct +{ + uint8_t version; ///< See ::MBG_SNMP_VERSIONS + uint8_t access_type; ///< See ::MBG_SNMP_ACCESS_TYPES, ignore in trap settings + uint8_t reserved_1[2]; + uint32_t reserved_2[3]; + char community[MBG_MONITORING_STR_SIZE]; + +} MBG_SNMP_V12_SETTINGS; + +#define _mbg_swab_snmp_v12_settings( _p ) \ +do \ +{ \ +} while ( 0 ) + + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SNMP_V12_SETTINGS settings; + +} MBG_SNMP_V12_SETTINGS_IDX; + +#define _mbg_swab_snmp_v12_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v12_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct mbg_snmp_v12_info_s +{ + MBG_SNMP_V12_SETTINGS settings; + uint32_t reserved_1[4]; + +} MBG_SNMP_V12_INFO; + +#define _mbg_swab_snmp_v12_info( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v12_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SNMP_V12_INFO info; + +} MBG_SNMP_V12_INFO_IDX; + +#define _mbg_swab_snmp_v12_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v12_info( &(_p)->info ); \ +} while ( 0 ) + + + +typedef struct +{ + uint8_t timeout; ///< In seconds + uint8_t retries; + uint16_t reserved_1; + uint32_t reserved_2[3]; + char reserved_3[MBG_MONITORING_STR_SIZE]; ///< Future use + char reserved_4[MBG_MONITORING_STR_SIZE]; ///< Future use + MBG_SNMP_V12_SETTINGS v12_settings; + MBG_HOSTNAME receiver_addr; + uint16_t dest_port; ///< receiver destination port, 162 by default + uint16_t reserved_5; + +} MBG_SNMP_V12_TRAP_SETTINGS; + +#define _mbg_swab_snmp_v12_trap_settings( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v12_settings( &(_p)->v12_settings ); \ + _mbg_swab16( &(_p)->dest_port ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SNMP_V12_TRAP_SETTINGS settings; + +} MBG_SNMP_V12_TRAP_SETTINGS_IDX; + +#define _mbg_swab_snmp_v12_trap_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v12_trap_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct mbg_snmp_v12_trap_info_s +{ + MBG_SNMP_V12_TRAP_SETTINGS settings; + uint32_t reserved_1[4]; + +} MBG_SNMP_V12_TRAP_INFO; + +#define _mbg_swab_snmp_v12_trap_info( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v12_trap_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SNMP_V12_TRAP_INFO info; + +} MBG_SNMP_V12_TRAP_INFO_IDX; + +#define _mbg_swab_snmp_v12_trap_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v12_trap_info( &(_p)->info ); \ +} while ( 0 ) + + + +enum MBG_SNMP_V3_SEC_LEVELS +{ + MBG_SNMP_V3_SEC_LEVEL_NO_AUTH_NO_PRIV, + MBG_SNMP_V3_SEC_LEVEL_AUTH_NO_PRIV, + MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV, + N_MBG_SNMP_V3_SEC_LEVELS +}; + +#define MBG_SNMP_V3_SEC_LEVEL_STRS \ +{ \ + "No auth no priv", \ + "Auth no priv", \ + "Auth priv" \ +} + + +enum MBG_SNMP_V3_AUTH_PROTOCOLS +{ + MBG_SNMP_V3_AUTH_PROTOCOL_NONE, + MBG_SNMP_V3_AUTH_PROTOCOL_MD5, + MBG_SNMP_V3_AUTH_PROTOCOL_SHA, + N_MBG_SNMP_V3_AUTH_PROTOCOLS +}; + +#define MBG_SNMP_V3_AUTH_PROTOCOL_STRS \ +{ \ + "None", \ + "MD5", \ + "SHA" \ +} + + +enum MBG_SNMP_V3_PRIV_PROTOCOLS +{ + MBG_SNMP_V3_PRIV_PROTOCOL_NONE, + MBG_SNMP_V3_PRIV_PROTOCOL_DES, + MBG_SNMP_V3_PRIV_PROTOCOL_AES, + N_MBG_SNMP_V3_PRIV_PROTOCOLS +}; + + +#define MBG_SNMP_V3_PRIV_PROTOCOL_STRS \ +{ \ + "None", \ + "DES", \ + "AES" \ +} + + + +typedef struct +{ + uint8_t access_type; ///< See ::MBG_SNMP_ACCESS_TYPES, ignore in trap settings + uint8_t sec_level; ///< See ::MBG_SNMP_V3_SEC_LEVELS + uint8_t auth_protocol; ///< See ::MBG_SNMP_V3_AUTH_PROTOCOLS if ::MBG_SNMP_V3_SETTINGS::sec_level + ///< is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_NO_PRIV or ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + uint8_t priv_protocol; ///< See ::MBG_SNMP_V3_PRIV_PROTOCOLS if ::MBG_SNMP_V3_SETTINGS::sec_level + ///< is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + uint16_t flags; ///< See ::MBG_SNMP_FLAG_MSKS + uint16_t reserved_0; + uint32_t reserved_1[3]; + char user_name[MBG_MONITORING_STR_SIZE]; ///< User name used for authentication, always required. + char auth_passwd[MBG_MONITORING_STR_SIZE]; ///< Password associated with ::MBG_SNMP_V3_SETTINGS::user_name, if ::MBG_SNMP_V3_SETTINGS::auth_protocol + ///< is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_NO_PRIV or ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + char sec_engine_id[MBG_MONITORING_STR_SIZE]; ///< Mandatory for traps only + char context_engine_id[MBG_MONITORING_STR_SIZE]; ///< Ignore + char context_name[MBG_MONITORING_STR_SIZE]; ///< Ignore + char reserved_2[MBG_MONITORING_STR_SIZE]; ///< Future use + char reserved_3[MBG_MONITORING_STR_SIZE]; ///< Future use + char priv_passwd[MBG_MONITORING_STR_SIZE]; ///< Encryption passwd if ::MBG_SNMP_V3_SETTINGS::auth_protocol is ::MBG_SNMP_V3_SEC_LEVEL_AUTH_PRIV + uint32_t boots; ///< Number of system/deamon restarts -> Ignore + uint32_t time; ///< Timeticks since last "boots" event -> Ignore + uint32_t reserved_4[2]; + +} MBG_SNMP_V3_SETTINGS; + +#define _mbg_swab_snmp_v3_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->boots ); \ + _mbg_swab32( &(_p)->time ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SNMP_V3_SETTINGS settings; + +} MBG_SNMP_V3_SETTINGS_IDX; + +#define _mbg_swab_snmp_v3_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v3_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct mbg_snmp_v3_info_s +{ + MBG_SNMP_V3_SETTINGS settings; + uint32_t reserved_1[4]; + +} MBG_SNMP_V3_INFO; + +#define _mbg_swab_snmp_v3_info( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v3_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SNMP_V3_INFO info; + +} MBG_SNMP_V3_INFO_IDX; + +#define _mbg_swab_snmp_v3_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v3_info( &(_p)->info ); \ +} while ( 0 ) + + + +typedef struct +{ + uint8_t timeout; ///< In seconds + uint8_t retries; + uint8_t reserved_1[2]; + uint32_t reserved_2[3]; + MBG_SNMP_V3_SETTINGS v3_settings; + MBG_HOSTNAME receiver_addr; + uint16_t dest_port; ///< receiver destination port, 162 by default + uint16_t reserved_3; + +} MBG_SNMP_V3_TRAP_SETTINGS; + +#define _mbg_swab_snmp_v3_trap_settings( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v3_settings( &(_p)->v3_settings ); \ + _mbg_swab16( &(_p)->dest_port ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SNMP_V3_TRAP_SETTINGS settings; + +} MBG_SNMP_V3_TRAP_SETTINGS_IDX; + +#define _mbg_swab_snmp_v3_trap_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v3_trap_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct mbg_snmp_v3_trap_info_s +{ + MBG_SNMP_V3_TRAP_SETTINGS settings; + uint32_t reserved_1[4]; + +} MBG_SNMP_V3_TRAP_INFO; + +#define _mbg_swab_snmp_v3_trap_info( _p ) \ +do \ +{ \ + _mbg_swab_snmp_v3_trap_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SNMP_V3_TRAP_INFO info; + +} MBG_SNMP_V3_TRAP_INFO_IDX; + +#define _mbg_swab_snmp_v3_trap_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_snmp_v3_trap_info( &(_p)->info ); \ +} while ( 0 ) + + + +/* If ::MBG_MONITORING_TYPE_MSK_EVENTS is set in ::MBG_MONITORING_LIMITS::supp_types */ + + +enum MBG_EVENT_STR_FMTS +{ + MBG_EVENT_STR_FMT_JSON, + N_MBG_EVENT_STR_FMTS +}; + + +enum MBG_EVENT_STR_FMT_MSKS +{ + MBG_EVENT_STR_FMT_JSON_MSK = (1UL << MBG_EVENT_STR_FMT_JSON) +}; + + +#define MBG_EVENT_STR_FMT_STRS \ +{ \ + "JSON" \ +} + + +enum MBG_EVENT_DEV_IDS +{ + MBG_EVENT_DEV_ID_NONE, ///< No identifier added to the events + MBG_EVENT_DEV_ID_ALIAS, ///< Add alias from MBG_EVENT_GLB_SETTINGS as identifier to all events + MBG_EVENT_DEV_ID_SERNUM, ///< Add serial number as identifier to all events + N_MBG_EVENT_DEV_IDS +}; + + +enum MBG_EVENT_DEV_ID_MSKS +{ + MBG_EVENT_DEV_ID_NONE_MSK = ( 1UL << MBG_EVENT_DEV_ID_NONE ), ///< See ::MBG_EVENT_DEV_ID_NONE + MBG_EVENT_DEV_ID_ALIAS_MSK = ( 1UL << MBG_EVENT_DEV_ID_ALIAS ), ///< See ::MBG_EVENT_DEV_ID_ALIAS + MBG_EVENT_DEV_ID_SERNUM_MSK = ( 1UL << MBG_EVENT_DEV_ID_SERNUM ) ///< See ::MBG_EVENT_DEV_ID_SERNUM +}; + + +#define MBG_EVENT_DEV_ID_STRS \ +{ \ + "None", \ + "Alias", \ + "Serial Number" \ +} + + +enum MBG_EVENT_GLB_FLAGS +{ + MBG_EVENT_GLB_FLAG_FUE, ///< Forward unknown events. This is not relevant for mbgdevman + ///< that always gets all events. It's important for syslog, SNMP, email, etc.. + ///< to avoid that alarming systems react furious to unknown events. + N_MBG_EVENT_GLB_FLAGS +}; + + +enum MBG_EVENT_GLB_FLAG_MSKS +{ + MBG_EVENT_GLB_FLAG_FUE_MSK = ( 1UL << MBG_EVENT_GLB_FLAG_FUE ) ///< See ::MBG_EVENT_GLB_FLAG_FUE +}; + + +typedef struct +{ + uint8_t format; ///< See ::MBG_EVENT_STR_FMTS + uint8_t dev_id; ///< See ::MBG_EVENT_DEV_IDS + uint8_t flags; ///< See ::MBG_EVENT_GLB_FLAG_MSKS + uint8_t reserved_1[5]; + + char alias[16]; ///< Alias of this device, see ::MBG_EVENT_DEV_ID_ALIAS + + uint32_t reserved_3[4]; + +} MBG_EVENT_GLB_SETTINGS; + +#define _mbg_swab_event_glb_settings( _p ) \ +do \ +{ \ +} while ( 0 ) + + +typedef struct mbg_event_glb_info_s +{ + MBG_EVENT_GLB_SETTINGS settings; ///< See ::MBG_EVENT_GLB_SETTINGS + + uint16_t num_events; ///< Supported number of events. See ::MBG_EVENT_TYPES + uint16_t supp_formats; ///< Supported format (::MBG_EVENT_STR_FMTS) in ::MBG_EVENT_STATUS::data + uint16_t supp_dev_ids; ///< Supported dev ids (::MBG_EVENT_DEV_IDS) that can be added to each ::MBG_EVENT_STATUS::data + uint8_t supp_flags; ///< Supported global settings flags. See ::MBG_EVENT_GLB_FLAG_MSKS + uint8_t reserved_1; + + uint32_t reserved_2[3]; + +} MBG_EVENT_GLB_INFO; + +#define _mbg_swab_event_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_event_glb_settings( (_p) ); \ + _mbg_swab16( &(_p)->num_events ); \ + _mbg_swab16( &(_p)->supp_formats ); \ + _mbg_swab16( &(_p)->supp_dev_ids ); \ +} while ( 0 ) + + + +enum MBG_EVENT_TYPES +{ + MBG_EVENT_TYPE_NTP_STATE, + MBG_EVENT_TYPE_HEARTBEAT, + MBG_EVENT_TYPE_RECEIVER_STATE, + MBG_EVENT_TYPE_LEAP_SECOND, + MBG_EVENT_TYPE_PTP_STATE, + MBG_EVENT_TYPE_SYSREF_MASTER_REF, + MBG_EVENT_TYPE_PS_STATE, + MBG_EVENT_TYPE_REBOOT, + MBG_EVENT_TYPE_MEMORY, + MBG_EVENT_TYPE_CPU_LOAD, + MBG_EVENT_TYPE_TEMPERATURE, + MBG_EVENT_TYPE_NW_LINK, + MBG_EVENT_TYPE_CONFIG, + MBG_EVENT_TYPE_LOGIN, + MBG_EVENT_TYPE_WATCHDOG, + N_MBG_EVENT_TYPES +}; + +#define MBG_EVENT_TYPE_STRS \ +{ \ + "NTP state", \ + "Heartbeat", \ + "Receiver state", \ + "Leap second", \ + "PTP state", \ + "Master reference changed", \ + "Power supply state", \ + "Reboot", \ + "Memory", \ + "CPU load", \ + "Temperature", \ + "Network link", \ + "Configuration", \ + "Login", \ + "Watchdog" \ +} + + +enum MBG_EVENT_SEVERITIES +{ + MBG_EVENT_SEVERITY_OK, + MBG_EVENT_SEVERITY_INFO, + MBG_EVENT_SEVERITY_WARNING, + MBG_EVENT_SEVERITY_ERROR, + MBG_EVENT_SEVERITY_CRITICAL, + N_MBG_EVENT_SEVERITIES +}; + +#define MBG_EVENT_SEVERITY_STRS \ +{ \ + "OK", \ + "Info", \ + "Warning", \ + "Error", \ + "Critical" \ +} + +typedef struct +{ + uint16_t triggers; ///< See ::MBG_MONITORING_TYPE_MSKS if set in ::MBG_MONITORING_LIMITS::supp_types + uint16_t interval; ///< [s], only if ::MBG_EVENT_SUPP_FLAG_INTERVAL is set in ::MBG_EVENT_INFO::supp_flags, else 0. + uint16_t reserved_1; + uint16_t reserved_2; + uint32_t reserved_3[6]; + +} MBG_EVENT_SETTINGS; + +#define _mbg_swab_event_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->triggers ); \ + _mbg_swab16( &(_p)->interval ); \ +} while ( 0 ) + + + +/** + * @brief Structure for monitoring event settings + * + * @see ::MBG_EVENT_INFO_IDX + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_EVENT_SETTINGS settings; + +} MBG_EVENT_SETTINGS_IDX; + +#define _mbg_swab_event_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_event_settings( &(_p)->settings ); \ +} while ( 0 ) + + + +enum MBG_EVENT_SUPP_FLAGS +{ + MBG_EVENT_SUPP_FLAG_INTERVAL, ///< Event can be sent cyclically + N_MBG_EVENT_SUPP_FLAGS +}; + + +enum MBG_EVENT_SUPP_FLAG_MSKS +{ + MBG_EVENT_SUPP_FLAG_MSK_INTERVAL = ( 1UL << MBG_EVENT_SUPP_FLAG_INTERVAL ) +}; + + + +/** + * @defgroup group_mbg_event_info_indexes Monitoring Event Info Indexes + * + * It's very important to understand how to use event indexes properly. + * In general, think of a management master system (MMS) + * like a LANTIME that is able to send its own events like "NTP not sync" + * and that is even able to send/forward events from other IMS modules + * like "CLK1 Antenna Disconnected". In case it is an event of the MMS + * itself, indexes in ::MBG_EVENT_INFO should be set to its "own" values below. + * But in case it is an event of an "IMS slave card" like a GPS180 + * at least ::MBG_EVENT_INFO::slot_type and ::MBG_EVENT_INFO::slot_type_id + * should be set. Most events will likely not support a port or a foreign + * chassis, so set ::MBG_EVENT_INFO::port_idx to ::MBG_INV_EVENT_PORT and/or + * ::MBG_EVENT_INFO::chassis_idx to ::MBG_OWN_EVENT_CHASSIS. + * Please be aware that there are IMS modules like SSP100 that tend to be + * "IMS slave cards", but they are, in fact, MMS because most of the time + * they are not connected to the main CPU via USB and + * therefore they send their "own" events. + * + * @{ */ + +#define MBG_OWN_EVENT_CHASSIS 0xFF ///< See ::MBG_EVENT_INFO::chassis_idx +#define MBG_OWN_EVENT_SLOT_TYPE 0xFF ///< See ::MBG_EVENT_INFO::slot_type +#define MBG_OWN_EVENT_SLOT_TYPE_ID 0xFF ///< See ::MBG_EVENT_INFO::slot_type_id +#define MBG_INV_EVENT_PORT 0xFF ///< See ::MBG_EVENT_INFO::port_idx +#define MBG_INV_EVENT_INST 0xFF ///< See ::MBG_EVENT_INFO::inst_idx + +/** @} defgroup group_mbg_event_info_indexes */ + + +typedef struct +{ + MBG_EVENT_SETTINGS settings; ///< See ::MBG_EVENT_SETTINGS + uint16_t type; ///< See ::MBG_EVENT_TYPES + uint8_t chassis_idx; ///< Index of the associated IMS chassis, or ::MBG_OWN_EVENT_CHASSIS + uint8_t slot_type; ///< See ::XBP_NODE_INFO::slot_type, or ::MBG_OWN_EVENT_SLOT_TYPE + uint8_t port_idx; ///< Index of the associated IO port, or ::MBG_INV_EVENT_PORT + uint8_t reserved_1; + uint16_t reserved_2; + + uint8_t slot_type_id; ///< See ::XBP_NODE_INFO::slot_type_id, or ::MBG_OWN_EVENT_SLOT_TYPE_ID + uint8_t inst_idx; ///< Instance index since one port might have multiple instances of the same type. + ///< For example, PTP is hopefully capable to do so one day. + ///< Use ::MBG_INV_EVENT_INST to not show the instance number explicitly, + ///< e.g. you only have got one instance. + uint16_t supp_flags; ///< See ::MBG_EVENT_SUPP_FLAG_MSKS + uint16_t supp_triggers; ///< See ::MBG_MONITORING_TYPE_MSKS + uint16_t reserved_3; ///< Future use + + uint32_t reserved_4[8]; + +} MBG_EVENT_INFO; + +#define _mbg_swab_event_info( _p ) \ +do \ +{ \ + _mbg_swab_event_settings( &(_p)->settings ); \ + _mbg_swab16( &(_p)->type ); \ + _mbg_swab16( &(_p)->value_dict_entries ); \ + _mbg_swab16( &(_p)->supp_flags ); \ + _mbg_swab16( &(_p)->supp_triggers ); \ +} while ( 0 ) + + + +/** + * @brief Structure for monitoring event info + * + * @note idx represents the event type, see ::MBG_EVENT_TYPES + * Before requesting the struct, its availability should be checked + * in ::MBG_EVENT_GLB_INFO::num_events. + * + * @see ::MBG_EVENT_TYPES + * @see ::MBG_EVENT_GLB_INFO + */ +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_EVENT_INFO info; + +} MBG_EVENT_INFO_IDX; + +#define _mbg_swab_event_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_event_info( &(_p)->info ); \ +} while ( 0 ) + + +#define MBG_EVT_ST_MAX_DATA_LEN 480 + +typedef struct +{ + uint32_t last_changed; ///< Unix timestamp when this event state has been changed + uint32_t reserved_1[2]; ///< Future use + uint8_t severity; ///< See ::MBG_EVENT_SEVERITIES + uint8_t reserved_2[3]; ///< Future use + + uint8_t data[MBG_EVT_ST_MAX_DATA_LEN]; ///< The event value in the configured format, see ::MBG_EVENT_GLB_SETTINGS::format + +} MBG_EVENT_STATUS; + +#define _mbg_swab_event_status( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->last_changed ); \ +} while ( 0 ) + + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_EVENT_STATUS status; + +} MBG_EVENT_STATUS_IDX; + +#define _mbg_swab_event_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_event_status( &(_p)->status ); \ +} while ( 0 ) + + + +enum MBG_SYSLOG_FLAGS +{ + MBG_SYSLOG_FLAG_NULL_TIMESTAMP, ///< Receiver should use his own timestamp + N_MBG_SYSLOG_FLAGS +}; + + +enum MBG_SYSLOG_FLAG_MSKS +{ + MBG_SYSLOG_FLAG_MSK_NULL_TIMESTAMP = (1UL << MBG_SYSLOG_FLAG_NULL_TIMESTAMP), ///< See ::MBG_SYSLOG_FLAG_NULL_TIMESTAMP +}; + + +enum MBG_SYSLOG_PROTOCOLS +{ + MBG_SYSLOG_PROTOCOL_UDP, + MBG_SYSLOG_PROTOCOL_TCP, + N_MBG_SYSLOG_PROTOCOLS +}; + +#define MBG_SYSLOG_PROTOCOL_STRS \ +{ \ + "UDP", \ + "TCP" \ +} + + +enum MBG_SYSLOG_PROTOCOL_MSKS +{ + MBG_SYSLOG_PROTOCOL_MSK_UDP = (1UL << MBG_SYSLOG_PROTOCOL_UDP), ///< See ::MBG_SYSLOG_PROTOCOL_UDP + MBG_SYSLOG_PROTOCOL_MSK_TCP = (1UL << MBG_SYSLOG_PROTOCOL_TCP) ///< See ::MBG_SYSLOG_PROTOCOL_TCP +}; + + +typedef struct +{ + uint8_t num_servers; ///< Number of configured servers + uint8_t reserved_1[3]; + uint32_t reserved_2[3]; + +} MBG_SYSLOG_GLB_SETTINGS; + +#define _mbg_swab_syslog_glb_settings( _p ) \ +do \ +{ \ +} while ( 0 ) + + +typedef struct mbg_syslog_glb_info_s +{ + MBG_SYSLOG_GLB_SETTINGS settings; ///< MBG_SYSLOG_GLB_SETTINGS + + uint8_t max_servers; ///< Maximum number of configurable servers + uint8_t reserved_1[3]; + uint32_t supp_flags; ///< See ::MBG_SYSLOG_FLAG_MSKS + uint32_t supp_protocols; ///< See ::MBG_SYSLOG_PROTOCOL_MSKS + + uint32_t reserved_2[5]; + +} MBG_SYSLOG_GLB_INFO; + +#define _mbg_swab_syslog_glb_info( _p ) \ +do \ +{ \ + _mbg_swab_syslog_glb_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->supp_flags ); \ + _mbg_swab32( &(_p)->supp_protocols ); \ +} while ( 0 ) + + +typedef struct +{ + char host[MBG_MAX_HOSTNAME_LEN]; + uint8_t protocol; ///< See ::MBG_SYSLOG_PROTOCOLS + uint8_t reserved_1; + uint16_t port; ///< Protocol port + uint32_t flags; ///< See ::MBG_SYSLOG_FLAG_MSKS + uint32_t reserved_3[6]; + +} MBG_SYSLOG_SETTINGS; + +#define _mbg_swab_syslog_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->port ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_SYSLOG_SETTINGS settings; + MBG_MSG_IDX_32 idx; + +} MBG_SYSLOG_SETTINGS_IDX; + +#define _mbg_swab_syslog_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab_syslog_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_SYSLOG_SETTINGS settings; ///< See ::MBG_SYSLOG_SETTINGS + uint32_t reserved[8]; + +} MBG_SYSLOG_INFO; + +#define _mbg_swab_syslog_info( _p ) \ +do \ +{ \ + _mbg_swab_syslog_settings( &(_p)->settings ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_SYSLOG_INFO info; ///< See ::MBG_SYSLOG_INFO + MBG_MSG_IDX_32 idx; + +} MBG_SYSLOG_INFO_IDX; + +#define _mbg_swab_syslog_info_idx( _p ) \ +do \ +{ \ + _mbg_swab_syslog_info( &(_p)->info ); \ + _mbg_swab32( &(_p)->idx ); \ +} while ( 0 ) + + +/** @} defgroup group_monitoring */ + + +/** + * @defgroup group_tainted_cfg Tainted config + * + * @note This structure and its definitions are only supported by a device + * if ::MBG_XFEATURE_TAINTED_CFG is set in the extended device features. + * Feature has a list of configuration counters for several sub-features. + * Each time the config of a sub-feature changes, its counter in this structure + * is increased to indicate the config change. Thus, software can read this + * structure and request the changed config. Also used for push notifications. + * + * TODO Add proper Doxygen documentation + * + * @{ */ + + +#define MBG_TAINTED_CFG_BYTES 256 +#define MBG_TAINTED_CFG_FLAG_BYTES (MBG_TAINTED_CFG_BYTES >> 3) + +/** + * @brief Array positions in ::MBG_TAINTED_CFG::tainted_cfgs + * + */ +enum MBG_TAINTED_CFGS +{ + MBG_TAINTED_CFG_INV = -1, + MBG_TAINTED_CFG_SNMP, + MBG_TAINTED_CFG_EMAIL, + MBG_TAINTED_CFG_SYSLOG, + MBG_TAINTED_CFG_EVENTS, + MBG_TAINTED_CFG_IOPORTS, + MBG_TAINTED_CFG_NTP, + MBG_TAINTED_CFG_XBP, + MBG_TAINTED_CFG_NETWORK, + MBG_TAINTED_CFG_USERS, + MBG_TAINTED_CFG_FIRMWARE, + MBG_TAINTED_CFG_XMR, + MBG_TAINTED_CFG_TIMECODE_RX, + MBG_TAINTED_CFG_TIMECODE_TX, + MBG_TAINTED_CFG_HAVEQUICK, + MBG_TAINTED_CFG_GPIO, + MBG_TAINTED_CFG_UART, + MBG_TAINTED_CFG_PROG_OUT, + MBG_TAINTED_CFG_VAR_SYNTH, + MBG_TAINTED_CFG_TIMESCALE, + MBG_TAINTED_CFG_IGNLOCK, + MBG_TAINTED_CFG_GNSSMODE, + MBG_TAINTED_CFG_EF, + MBG_TAINTED_CFG_TZDL, + MBG_TAINTED_CFG_CABLE_LENGTH, + MBG_TAINTED_CFG_DATABASE, + MBG_TAINTED_CFG_PTP_NG, + MBG_TAINTED_CFG_SYS_REF, + MBG_TAINTED_CFG_TR_DIST, + N_MBG_TAINTED_CFGS +}; + +typedef struct +{ + uint8_t tainted_cfgs[MBG_TAINTED_CFG_BYTES]; ///< See ::MBG_TAINTED_CFGS + uint8_t supp_cfgs[MBG_TAINTED_CFG_FLAG_BYTES]; ///< See ::MBG_TAINTED_CFGS + uint32_t reserved[4]; ///< Future use + +} MBG_TAINTED_CFG; + +#define _mbg_swab_tainted_cfg( _p ) do {} while ( 0 ) + +#define _mbg_tainted_cfg_increase(c, cfg) \ +do \ +{ \ + if ( ( c >= MBG_TAINTED_CFG_BYTES ) || ( c >= N_MBG_TAINTED_CFGS ) ) \ + break; \ + \ + ++(cfg)->tainted_cfgs[ c ]; \ + \ +} while ( 0 ); + +/** + * @brief Set a supported tainted config bit in a ::MBG_TAINTED_CFG::supp_cfgs + * + * Should be used by the firmware only to set one of the supported ::N_MBG_TAINTED_CFGS + * bits in :MBG_TAINTED_CFG::supp_cfgs. + * + * @param[in] _cfg_bit One of the ::MBG_TAINTED_CFGS + * @param[in] _tainted_cfg Pointer to ::MBG_TAINTED_CFG + */ +#define _set_supp_tainted_cfg_bit( _cfg_bit, _tainted_cfg ) \ + _set_array_bit( _cfg_bit, (_tainted_cfg)->supp_cfgs, MBG_TAINTED_CFG_FLAG_BYTES ) + +/** + * @brief Clear a supported tainted config bit in a ::MBG_TAINTED_CFG::supp_cfgs + * + * Should be used by the firmware only to clear one of the supported ::N_MBG_TAINTED_CFGS + * bits in :MBG_TAINTED_CFG::supp_cfgs. + * + * @param[in] _cfg_bit One of the ::MBG_TAINTED_CFGS + * @param[in] _tainted_cfg Pointer to ::MBG_TAINTED_CFG + */ +#define _clear_supp_tainted_cfg_bit( _cfg_bit, _tainted_cfg ) \ + _clear_array_bit( _cfg_bit, (_tainted_cfg)->supp_cfgs, MBG_TAINTED_CFG_FLAG_BYTES ) + +/** + * @brief Check for a supported tainted config bit in a ::MBG_TAINTED_CFG::supp_cfgs + * + * @param[in] _cfg_bit One of the ::MBG_TAINTED_CFGS + * @param[in] _tainted_cfg Pointer to ::MBG_TAINTED_CFG + */ +#define _check_supp_tainted_cfg_bit( _cfg_bit, _tainted_cfg ) \ + check_feat_supp_byte_array( _cfg_bit, (_tainted_cfg)->supp_cfgs, MBG_TAINTED_CFG_FLAG_BYTES ) + +/** @} defgroup group_tainted_cfg */ + + +/** + * @defgroup group_user_mngmnt User Management + * + * @note These structures and definitions provide an extended user management + * for Meinberg devices based on the Linux user management and the files + * /etc/passwd and /etc/shadow. They are only supported by a device, + * if ::MBG_XFEATURE_USER_MNGMNT is set in the extended device features. + * + * @{ */ + +typedef enum _mbg_user_perms +{ + USER_PERM_SYSTEM, ///< permission to read/write system related structures + ///< ::GPS_SCU_STAT + ///< ::GPS_TIME_SCALE + ///< ::GPS_TZDL + ///< ::PZF_TZCODE + ///< ::GPS_REBOOT + ///< ::MBG_TLV_FEAT_TYPE_DIAG_FILE + ///< ::GPS_TAINTED_CFG + ///< ::GPS_XBP_LIMITS + ///< ::GPS_XBP_NODE_LIMITS + ///< ::GPS_XBP_NODE_INFO_IDX + USER_PERM_RECEIVER, ///< permission to read/write receiver related structures + ///< ::GPS_TIME + ///< ::GPS_ANT_CABLE_LENGTH + ///< ::GPS_GNSS_MODE + ///< ::GPS_IGNORE_LOCK + ///< ::GPS_SAVE_CFG + ///< ::GPS_POS_XYZ + ///< ::GPS_POS_LLA + ///< ::GPS_STAT_INFO + ///< ::GPS_SV_INFO + ///< ::GPS_GNSS_SAT_INFO_IDX + ///< ::GPS_GNSS_SV_STATUS_IDX + ///< ::GPS_CLR_EVT_LOG + ///< ::GPS_NUM_EVT_LOG_ENTRIES + ///< ::GPS_FIRST_EVT_LOG_ENTRY + ///< ::GPS_NEXT_EVT_LOG_ENTRY + USER_PERM_MRS, ///< permission to read/write MRS related structures + ///< ::GPS_XMR_INSTANCES + ///< ::GPS_XMR_INFO_IDX + ///< ::GPS_XMR_EXT_SRC_INFO_IDX + ///< ::GPS_XMR_STATUS_IDX + ///< ::GPS_XMR_HOLDOVER_STATUS + ///< ::GPS_XMR_STATS_IDX + ///< ::GPS_XMR_METRICS_IDX + ///< ::GPS_SYS_REF_LIMITS + ///< ::GPS_SYS_REF_GLB_STATUS + ///< ::GPS_SYS_REF_SRC_INFO_IDX + ///< ::GPS_SYS_REF_SRC_STATUS_IDX + USER_PERM_SERIAL, ///< permission to read/write serial port related structures + ///< ::GPS_PORT_INFO_IDX + ///< ::GPS_STR_TYPE_INFO_IDX + USER_PERM_IOPORTS, ///< permission to read/write IO port related structures + ///< ::GPS_IRIG_RX_INFO + ///< ::GPS_RAW_IRIG_DATA + ///< ::GPS_REF_OFFS + ///< ::GPS_IRIG_RX_SETTINGS + ///< ::GPS_IRIG_TX_INFO + ///< ::GPS_SYNTH + ///< ::GPS_ENABLE_FLAGS + ///< ::GPS_IRIG_TX_SETTINGS + ///< ::GPS_POUT_INFO_IDX + ///< ::GPS_POUT_SETTINGS_IDX + ///< ::GPS_GPIO_CFG_LIMITS + ///< ::GPS_GPIO_INFO_IDX + ///< ::GPS_GPIO_SETTINGS_IDX + ///< ::GPS_GPIO_STATUS_IDX + ///< ::GPS_IO_PORT_LIMITS + ///< ::GPS_IO_PORT_INFO_IDX + ///< ::GPS_IO_PORT_TYPE_INFO_IDX + ///< ::GPS_IO_PORT_SETTINGS_IDX + ///< ::GPS_IO_PORT_STATUS_IDX + ///< ::GPS_UCAP_NET_GLB_INFO + ///< ::GPS_UCAP_NET_RECV_INFO_IDX + ///< ::GPS_CLR_UCAP_BUFF + ///< ::GPS_UCAP + USER_PERM_MONITORING, ///< permission to read/write monitoring related structures + ///< ::GPS_MONITORING_LIMITS + ///< ::GPS_SNMP_GLB + ///< ::GPS_SNMP_V12_IDX + ///< ::GPS_SNMP_V12_TRAP_IDX + ///< ::GPS_SNMP_V3_IDX + ///< ::GPS_SNMP_V3_TRAP_IDX + ///< ::GPS_EVENT_IDX + ///< ::GPS_EVENT_STAT_IDX + ///< ::GPS_NUM_EVT_LOG_ENTRIES + ///< ::GPS_FIRST_EVT_LOG_ENTRY + ///< ::GPS_NEXT_EVT_LOG_ENTRY + ///< ::GPS_CLR_EVT_LOG + ///< ::GPS_SYSLOG_GLB_INFO + ///< ::GPS_SYSLOG_INFO_IDX + USER_PERM_NETWORK, ///< permission to read/write network related structures + ///< ::GPS_NET_GLB_CFG + ///< ::GPS_NET_STAT_GLB_CFG + ///< ::GPS_NET_INTF_LINK_IDX + ///< ::GPS_NET_STAT_INTF_LINK_IDX + ///< ::GPS_NET_INTF_ADDR_IDX + ///< ::GPS_NET_STAT_INTF_ADDR_IDX + ///< ::GPS_NET_INTF_ROUTE_IDX + ///< ::GPS_NET_STAT_INTF_ROUTE_IDX + ///< ::GPS_NET_DNS_SRVR + ///< ::GPS_NET_STAT_DNS_SRVR + ///< ::GPS_NET_DNS_SRCH_DOM + ///< ::GPS_NET_STAT_DNS_SRCH_DOM + ///< ::GPS_LAN_IF_INFO + ///< ::GPS_IP4_SETTINGS + ///< ::GPS_IP4_STATE + USER_PERM_NTP, ///< permission to read/write NTP related structures + ///< ::GPS_NTP_GLB_CFG + ///< ::GPS_NTP_SYS_STATE + ///< ::GPS_NTP_SYMM_KEY_LIMITS + ///< ::GPS_NTP_SYMM_KEY_CFG + ///< ::GPS_NTP_TRUSTED_KEY_CFG + ///< ::GPS_NTP_CLNT_MODE_CFG + ///< ::GPS_NTP_PEER_SETTINGS_IDX + ///< ::GPS_NTP_PEER_STATE_IDX + ///< ::GPS_NTP_SRV_MODE_CFG + ///< ::GPS_NTP_REFCLK_CFG + ///< ::GPS_NTP_REFCLK_STATE_IDX + ///< ::GPS_NTP_MISC_LIMITS + ///< ::GPS_NTP_MISC_ORPHAN_MODE + USER_PERM_PTP, ///< permission to read/write PTP related structures + ///< ::GPS_PTP_CFG + ///< ::GPS_PTP_STATE + ///< ::GPS_PTP_UC_MASTER_CFG_LIMITS + ///< ::GPS_PTP_UC_MASTER_CFG + ///< ::GPS_PTP_V2_DEFAULT_DS + ///< ::GPS_PTP_V2_CURRENT_DS + ///< ::GPS_PTP_V2_PARENT_DS + ///< ::GPS_PTP_V2_TIME_PROP_DS + ///< ::GPS_PTP_V2_PORT_DS_IDX + ///< ::GPS_PTP_V1_DEFAULT_DS + ///< ::GPS_PTP_V1_CURRENT_DS + ///< ::GPS_PTP_V1_PARENT_DS + ///< ::GPS_PTP_V1_TIME_PROP_DS + ///< ::GPS_PTP_V1_PORT_DS_IDX + ///< ::GPS_PTP_NG_GLB_INFO + ///< ::GPS_PTP_NG_TSTAMPER_INFO_IDX + ///< ::GPS_PTP_NG_INSTC_INFO_IDX + ///< ::GPS_PTP_NG_INSTC_STATUS_IDX + ///< ::GPS_PTP_NG_UC_MASTER_INFO_IDX + USER_PERM_FDM, ///< permission to read/write FDM related structures + ///< ::GPS_FDM_LIMITS + ///< ::GPS_FDM_INFO + ///< ::GPS_FDM_STATE + ///< ::GPS_FDM_SETTINGS + ///< ::GPS_FDM_OUTPUT_INFO_IDX + ///< ::GPS_FDM_OUTPUT_SETTINGS_IDX + ///< ::GPS_FDM_OUTPUT_STATE_IDX + ///< ::GPS_FDM_SET_TD + USER_PERM_SENSORS, ///< permission to read sensors related structures + ///< ::GPS_IMS_STATE + ///< ::GPS_IMS_SENSOR_STATE_IDX + USER_PERM_PASSWORD, ///< permission to read/change the user password + USER_PERM_USERS, ///< permission to read/write user related structures + ///< ::GPS_USER_MNGMNT_INFO + ///< ::GPS_USER_INFO_IDX + ///< ::GPS_USER_LEVEL_INFO_IDX + ///< ::GPS_USER_STATUS_IDX + USER_PERM_FIRMWARE, ///< permission to read/write firmware of a device + ///< ::GPS_FW_GLB_INFO + ///< ::GPS_FW_INFO_IDX + ///< ::GPS_FW_UFU_INFO_IDX + ///< ::GPS_FW_ACTIVATE + ///< ::GPS_FW_DELETE + ///< ::GPS_FW_UFU_FLASH + ///< ::MBG_TLV_FEAT_TYPE_FW_UPDATE + ///< ::MBG_TLV_FEAT_TYPE_UFU + ///< ::MBG_TLV_FEAT_TYPE_FW_ROLLBACK + USER_PERM_SERVICE, ///< permission to read/write service related structures + ///< ::GPS_SVC_MGMT_INFO + ///< ::GPS_SVC_INFO_IDX + ///< ::GPS_SVC_STATUS_IDX + ///< ::GPS_SVC_CTL_IDX + USER_PERM_DATABASE, ///< permission to read/write database related structures + ///< ::GPS_DATABASE_GLB_INFO + ///< ::GPS_DATABASE_INFO_IDX + N_USER_PERMS + +} MBG_USER_PERMS; + + +/** + * @brief Strings for defined user permissions + * + * @see ::MBG_USER_PERMS + */ +#define MBG_USER_PERM_STRS \ +{ \ + "System", \ + "Receiver", \ + "Ref. Sources", \ + "Serial Ports", \ + "IO Ports", \ + "Monitoring", \ + "Network", \ + "NTP", \ + "PTP", \ + "FDM", \ + "Sensors", \ + "Password", \ + "Users", \ + "Firmware", \ + "Services", \ + "Database" \ +} + + +typedef enum _mbg_user_scopes +{ + USER_SCOPE_STATUS_READ, + USER_SCOPE_CONFIG_READ, + USER_SCOPE_CONFIG_WRITE, + N_USER_SCOPES + +} MBG_USER_SCOPES; + + +typedef enum +{ + USER_SCOPE_STATUS_READ_MSK = ( 1UL << USER_SCOPE_STATUS_READ ), ///< See ::USER_SCOPE_STATUS_READ + USER_SCOPE_CONFIG_READ_MSK = ( 1UL << USER_SCOPE_CONFIG_READ ), ///< See ::USER_SCOPE_CONFIG_READ + USER_SCOPE_CONFIG_WRITE_MSK = ( 1UL << USER_SCOPE_CONFIG_WRITE ) ///< See ::USER_SCOPE_CONFIG_WRITE + +} MBG_USER_SCOPE_MSKS; + +/// @brief a combined permission mask to read configuration or status. +/// +/// In most cases the permission to read the configuration includes +/// the permission to read the status, anyway. +#define USER_SCOPE_CONFIG_OR_STATUS_READ_MSK \ + ( USER_SCOPE_CONFIG_READ_MSK | USER_SCOPE_STATUS_READ_MSK ) + + +#define MAX_USER_PERM_BYTES 64 +#define MAX_USER_PERM_BITS MAX_USER_PERM_BYTES * 8 + + +typedef enum +{ + USER_CHANNEL_WEB_INTERFACE, + USER_CHANNEL_MBGDEVMAN, + USER_CHANNEL_SHELL, + USER_CHANNEL_SNMP, + USER_CHANNEL_NETCONF, + N_USER_CHANNELS + +} MBG_USER_CHANNELS; + + +#define MAX_USER_CHANNEL_BYTES 16 +#define MAX_USER_CHANNEL_BITS MAX_USER_CHANNEL_BYTES * 8 + + +/** + * @brief Strings for defined user channels + * + * @see ::MBG_USER_CHANNELS + */ +#define MBG_USER_CHANNEL_STRS \ +{ \ + "Web Interface", \ + "Device Manager", \ + "Shell", \ + "SNMP", \ + "Netconf" \ +} + + +/** + * @brief A structure used to store user permissions. + * + * Up to ::MAX_USER_PERM_BITS totally can be stored. + * There should be one ::MBG_USER_PERM_BUF for status permissions, + * read configuration and write configuration permissions, each. + * + * @see ::MBG_USER_PERMS + * @see ::_set_user_perm + * @see ::_check_user_perm + */ +typedef struct mbg_user_perm_buf_s +{ + uint8_t b[MAX_USER_PERM_BYTES]; ///< buffer for user permissions, see ::_set_user_perm and ::_check_user_perm + +} MBG_USER_PERM_BUF; + + +/** + * @brief Set a user permission in a ::MBG_USER_PERM_BUF + * + * @param[in] _user_perm_bit One of ::MBG_USER_PERMS + * @param[in] _user_perm_buffp Pointer to an ::MBG_USER_PERM_BUF + */ +#define _set_user_perm( _user_perm_bit, _user_perm_buffp ) \ + _set_array_bit( _user_perm_bit, (_user_perm_buffp)->b, MAX_USER_PERM_BYTES ) + + +/** + * @brief Unset a user permission in a ::MBG_USER_PERM_BUF + * + * @param[in] _user_perm_bit One of ::MBG_USER_PERMS + * @param[in] _user_perm_buffp Pointer to an ::MBG_USER_PERM_BUF + */ +#define _clear_user_perm( _user_perm_bit, _user_perm_buffp ) \ + _clear_array_bit( _user_perm_bit, (_user_perm_buffp)->b, MAX_USER_PERM_BYTES ) + + +/** + * @brief Check a user permission in a ::MBG_USER_PERM_BUF + * + * @param[in] _user_perm_bit One of ::MBG_USER_PERMS + * @param[in] _user_perm_buffp Pointer to an ::MBG_USER_PERM_BUF + */ +#define _check_user_perm( _user_perm_bit, _user_perm_buffp ) \ + check_feat_supp_byte_array( _user_perm_bit, (_user_perm_buffp)->b, MAX_USER_PERM_BYTES ) + + +/** + * @brief A structure used to store user channels. + * + * Up to ::MAX_USER_CHANNEL_BITS totally can be stored. + * + * @see ::MBG_USER_CHANNELS + * @see ::_set_user_channel + * @see ::_check_user_channel + */ +typedef struct +{ + uint8_t b[MAX_USER_CHANNEL_BYTES]; ///< buffer for user channels, see ::_set_user_channel and ::_check_user_channel + +} MBG_USER_CHANNEL_BUF; + + +/** + * @brief Set a user channel in a ::MBG_USER_CHANNEL_BUF + * + * @param[in] _user_channel_bit One of ::MBG_USER_CHANNELS + * @param[in] _user_channel_buffp Pointer to an ::MBG_USER_CHANNEL_BUF + */ +#define _set_user_channel( _user_channel_bit, _user_channel_buffp ) \ + _set_array_bit( _user_channel_bit, (_user_channel_buffp)->b, MAX_USER_CHANNEL_BYTES ) + + +/** + * @brief Unset a user channel in a ::MBG_USER_CHANNEL_BUF + * + * @param[in] _user_channel_bit One of ::MBG_USER_CHANNELS + * @param[in] _user_channel_buffp Pointer to an ::MBG_USER_CHANNEL_BUF + */ +#define _clear_user_channel( _user_channel_bit, _user_channel_buffp ) \ + _clear_array_bit( _user_channel_bit, (_user_channel_buffp)->b, MAX_USER_CHANNEL_BYTES ) + + +/** + * @brief Check a user channel in a ::MBG_USER_CHANNEL_BUF + * + * @param[in] _user_channel_bit One of ::MBG_USER_CHANNELS + * @param[in] _user_channel_buffp Pointer to an ::MBG_USER_CHANNEL_BUF + */ +#define _check_user_channel( _user_channel_bit, _user_channel_buffp ) \ + check_feat_supp_byte_array( _user_channel_bit, (_user_channel_buffp)->b, MAX_USER_CHANNEL_BYTES ) + + +typedef enum +{ + USER_MNGMNT_SUPP_USER_CFG, ///< device supports user configuration, otherwise users are static + USER_MNGMNT_SUPP_USER_LEVEL_CFG, ///< device supports user level configuration, otherwise user levels are static + N_USER_MNGMNT_FLAGS + +} MBG_USER_MNGMNT_FLAGS; + + +typedef enum +{ + USER_MNGMNT_SUPP_USER_CFG_MASK = ( 1UL << USER_MNGMNT_SUPP_USER_CFG ), ///< See ::USER_MNGMNT_SUPP_USER_CFG + USER_MNGMNT_SUPP_USER_LEVEL_CFG_MASK = ( 1UL << USER_MNGMNT_SUPP_USER_LEVEL_CFG ) ///< See ::USER_MNGMNT_SUPP_USER_LEVEL_CFG + +} MBG_USER_MNGMNT_FLAG_MASKS; + + +typedef struct +{ + uint32_t num_users; ///< current number of users + uint32_t num_levels; ///< current number of users + uint32_t reserved_1[2]; ///< reserved, currently always 0 + + uint32_t flags; ///< flags, see ::MBG_USER_MNGMNT_FLAG_MASKS + + uint32_t reserved_2[16]; ///< reserved, currently always 0 + +} MBG_USER_MNGMNT_SETTINGS; + + +#define _mbg_swab_user_mngmnt_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->num_users ); \ + _mbg_swab32( &(_p)->num_levels ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_USER_MNGMNT_SETTINGS settings; ///< settings, see ::MBG_USER_MNGMNT_SETTINGS + + uint32_t n_supp_users; ///< supported number of users + uint32_t n_supp_levels; ///< supported number of user levels + + MBG_USER_CHANNEL_BUF supp_user_channels; ///< supported channels for internal users + MBG_USER_CHANNEL_BUF supp_lvl_channels; ///< supported channels for external users + MBG_USER_PERM_BUF supp_perms; ///< supported user permissions + + uint32_t supp_flags; ///< supported flags, see ::MBG_USER_MNGMNT_FLAG_MASKS + + uint32_t reserved[16]; ///< reserved, currently always 0 + +} MBG_USER_MNGMNT_INFO; + + +#define _mbg_swab_user_mngmnt_info( _p ) \ +do \ +{ \ + _mbg_swab_user_mngmnt_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->n_supp_users ); \ + _mbg_swab32( &(_p)->n_supp_levels ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +typedef enum +{ + USER_TYPE_USER, ///< standard system user + USER_TYPE_LEVEL, ///< user level for external authentication and as template for new users + N_USER_TYPES + +} MBG_USER_TYPE; + + +typedef enum +{ + USER_CFG_CAN_LOGIN, ///< the user is allowed to login (should not be set for root) + USER_CFG_CAN_REMOVE, ///< the user can be removed (should not be set for root) + USER_CFG_CAN_DISABLE_ON_FAILS, ///< the user supports the disabling after a number of login fails, see ::MBG_USER_SETTINGS::max_fails + USER_CFG_MULTI_SESSION, ///< allow user to login more than once (i.e. via TCP & Web) + USER_CFG_FORCE_CHANGE_ON_WARN, ///< user shall be forced to change the password on password warning + USER_CFG_FORCE_DISABLE_ON_EXP, ///< user account will immediately be disabled on password expiration, if this flags is not set, + ///< the user shall be forced to change the password on the next login attempt + USER_CFG_PASSWORD_CHANGED, ///< Indicates, that the password has been changed and needs to be crypted + USER_CFG_CAN_SHELL_SUDO, ///< The user is allowed to increase the privilege level by using sudo tool. + ///< Only relevant if user is allowed to use shell channel. + N_USER_CFG_FLAGS + +} MBG_USER_CFG_FLAGS; + + +typedef enum +{ + USER_CFG_CAN_LOGIN_MASK = ( 1UL << USER_CFG_CAN_LOGIN ), ///< See ::USER_CFG_CAN_LOGIN + USER_CFG_CAN_REMOVE_MASK = ( 1UL << USER_CFG_CAN_REMOVE ), ///< See ::USER_CFG_CAN_REMOVE + USER_CFG_CAN_DISABLE_ON_FAILS_MASK = ( 1UL << USER_CFG_CAN_DISABLE_ON_FAILS ), ///< See ::USER_CFG_CAN_DISABLE_ON_FAILS + USER_CFG_MULTI_SESSION_MASK = ( 1UL << USER_CFG_MULTI_SESSION ), ///< See ::USER_CFG_MULTI_SESSION + USER_CFG_FORCE_CHANGE_ON_WARN_MASK = ( 1UL << USER_CFG_FORCE_CHANGE_ON_WARN ), ///< See ::USER_CFG_FORCE_CHANGE_ON_WARN + USER_CFG_FORCE_DISABLE_ON_EXP_MASK = ( 1UL << USER_CFG_FORCE_DISABLE_ON_EXP ), ///< See ::USER_CFG_FORCE_DISABLE_ON_EXP + USER_CFG_PASSWORD_CHANGED_MASK = ( 1UL << USER_CFG_PASSWORD_CHANGED ), ///< See ::USER_CFG_PASSWORD_CHANGED + USER_CFG_CAN_SHELL_SUDO_MASK = ( 1UL << USER_CFG_CAN_SHELL_SUDO ) ///< See ::USER_CFG_CAN_SHELL_SUDO + +} MBG_USER_CFG_FLAG_MASKS; + + +#define MBG_MAX_USER_NAME_LEN 32 ///< See man page for 'useradd'. +#define MBG_MAX_USER_PASSWORD_LEN 128 + + +typedef struct +{ + char name[MBG_MAX_USER_NAME_LEN]; ///< user name + char password[MBG_MAX_USER_PASSWORD_LEN]; ///< user password, should only be set if it shall be changed + + uint32_t level_id; ///< unique id for user level, only used if ::MBG_USER_INFO::type is ::USER_TYPE_LEVEL + + uint32_t warn_days; ///< number of days, after which the user shall be warned about an upcoming password expiration, + uint32_t exp_days; ///< number of days, after which the password becomes invalid, see ::MBG_USER_INFO::password_doc, + uint32_t max_fails; ///< maximum number of login fails, before the user is disabled, + ///< only supported if ::USER_CFG_CAN_DISABLE_ON_FAILS_MASK + ///< all above values shall only be used, if they are not 0 + uint32_t flags; ///< flags, see ::MBG_USER_CFG_FLAG_MASKS + + MBG_USER_CHANNEL_BUF channels; ///< Channels, that are allowed for this user, see ::MBG_USER_CHANNEL_BUF + + MBG_USER_PERM_BUF stat_read_perm; ///< status read permission configuration, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS + MBG_USER_PERM_BUF cfg_read_perm; ///< config read permission configuration, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS + MBG_USER_PERM_BUF cfg_write_perm; ///< config write permission configuration, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS + + uint32_t reserved[8]; ///< reserved, currently always 0 + +} MBG_USER_SETTINGS; + + +#define _mbg_swab_user_settings( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->warn_days ); \ + _mbg_swab32( &(_p)->exp_days ); \ + _mbg_swab32( &(_p)->max_fails ); \ + _mbg_swab32( &(_p)->flags ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; ///< The index of the user. + MBG_USER_SETTINGS settings; ///< Settings, see ::MBG_USER_SETTINGS. + +} MBG_USER_SETTINGS_IDX; + + +#define _mbg_swab_user_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_user_settings( &(_p)->settings ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_USER_SETTINGS settings; + + uint8_t type; ///< type, see ::MBG_USER_TYPE + uint8_t reserved_1; ///< reserved, currently always 0 + uint16_t reserved_2; ///< reserved, currently always 0 + + uint32_t uid; ///< user id assigned by the OS + uint32_t gid; ///< group id + + uint32_t password_doc; ///< time of last password change (days since 1970) + + uint32_t supp_flags; ///< supported flags, see ::MBG_USER_CFG_FLAG_MASKS + uint32_t reserved_3[8]; ///< reserved, currently always 0 + +} MBG_USER_INFO; + + +#define _mbg_swab_user_info( _p ) \ +do \ +{ \ + _mbg_swab_user_settings( &(_p)->settings ); \ + _mbg_swab32( &(_p)->uid ); \ + _mbg_swab32( &(_p)->gid ); \ + _mbg_swab32( &(_p)->password_doc ); \ + _mbg_swab32( &(_p)->supp_flags ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; ///< the index of the user + MBG_USER_INFO info; ///< info, see ::MBG_USER_INFO + +} MBG_USER_INFO_IDX; + + +#define _mbg_swab_user_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_user_info( &(_p)->info ); \ +} while ( 0 ) + + +typedef enum +{ + USER_STAT_PASSWORD_WARN, ///< the user shall be warned about upcoming password expiration + USER_STAT_PASSWORD_EXP, ///< the user password has expired + USER_STAT_DISABLED_ON_EXP, ///< the user is disabled, because the password has expired + USER_STAT_DISABLED_ON_MAX_FAILS, ///< the user is disabled, because the max number of login fails has been exceeded + N_USER_STAT_FLAGS + +} MBG_USER_STAT_FLAGS; + + +typedef enum +{ + USER_STAT_PASSWORD_WARN_MASK = ( 1UL << USER_STAT_PASSWORD_WARN ), ///< See ::USER_STAT_PASSWORD_WARN + USER_STAT_PASSWORD_EXP_MASK = ( 1UL << USER_STAT_PASSWORD_EXP ), ///< See ::USER_STAT_PASSWORD_EXP + USER_STAT_DISABLED_ON_EXP_MASK = ( 1UL << USER_STAT_DISABLED_ON_EXP ), ///< See ::USER_STAT_DISABLED_ON_EXP + USER_STAT_DISABLED_ON_MAX_FAILS_MASK = ( 1UL << USER_STAT_DISABLED_ON_MAX_FAILS ) ///< See ::USER_STAT_DISABLED_ON_MAX_FAILS + +} MBG_USER_STAT_FLAG_MASKS; + + +typedef struct +{ + uint32_t flags; ///< flags, see ::MBG_USER_STAT_FLAG_MASKS + uint32_t login_cnt; ///< current number of active logins + uint32_t num_fails; ///< current number of unsuccessful login attempts + + MBG_USER_PERM_BUF stat_read_perm; ///< current status read permissions, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS + MBG_USER_PERM_BUF cfg_read_perm; ///< current config read permissions, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS + MBG_USER_PERM_BUF cfg_write_perm; ///< current config write permissions, see ::MBG_USER_PERM_BUF and ::MBG_USER_PERMS + + uint32_t reserved[16]; ///< reserved, currently always 0 + +} MBG_USER_STATUS; + + +#define _mbg_swab_user_status( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab32( &(_p)->login_cnt ); \ + _mbg_swab32( &(_p)->num_fails ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; ///< the index of the user + MBG_USER_STATUS status; ///< status, see ::MBG_USER_STATUS + +} MBG_USER_STATUS_IDX; + + +#define _mbg_swab_user_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_user_status( &(_p)->status ); \ +} while ( 0 ) + + +/** @} defgroup group_user_mngmnt */ + + + +/** + * @defgroup group_service_mngmnt Service Management + * + * @note These structures and definitions provide extended service management + * for Meinberg devices based on Linux / Windows. + * if ::MBG_XFEATURE_SERVICE is set in the extended device features. + * + * @{ */ + + +typedef enum +{ + MBG_SVC_TYPE_NTP, // Device supports NTP service (ntpd, or OpenNTP, etc ...) + MBG_SVC_TYPE_SNMP, // Device supports SNMP service (net-snmp, etc...) + N_MBG_SVC_TYPES + +} MBG_SERVICE_TYPES; + + +#define MBG_SERVICE_TYPE_STRS \ +{ \ + "NTP", \ + "SNMP" \ +} + + +typedef enum +{ + MBG_SVC_NTP_MSK = ( 1UL << MBG_SVC_TYPE_NTP ), ///< See ::MBG_SVC_TYPE_NTP + MBG_SVC_SNMP_MSK = ( 1UL << MBG_SVC_TYPE_SNMP ) ///< See ::MBG_SVC_TYPE_SNMP + +} MBG_SERVICE_MSKS; + + +typedef struct +{ + uint8_t num_services; ///< Current number of supported services + uint8_t reserved_1[3]; + uint32_t reserved_2[3]; + +} MBG_SERVICE_MGMT_INFO; + + +#define _mbg_swab_svc_mgmt_info( _p ) do {} while ( 0 ) + + +#define MBG_SVC_NAME_LEN 32 +#define MBG_SVC_CMD_LEN 192 + + +typedef enum +{ + MBG_SVC_UNKNOWN, + MBG_SVC_RUNNING, + MBG_SVC_STOPPED, + N_MBG_SVC_STATES + +} MBG_SERVICE_STATE; + + +#define MBG_SERVICE_STATE_STRS \ +{ \ + "Unknown", \ + "Running", \ + "Stopped" \ +} + + +typedef enum +{ + MBG_SVC_START, + MBG_SVC_STOP, + MBG_SVC_RESTART, + N_MBG_SVC_CTLS + +} MBG_SERVICE_CTL; + + +typedef struct +{ + char cmdline[MBG_SVC_CMD_LEN]; + uint8_t enabled; + uint8_t reserved_1[3]; + uint32_t reserved_2[3]; + +} MBG_SERVICE_SETTINGS; + + +#define _mbg_swab_svc_settings( _p ) do {} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SERVICE_SETTINGS settings; + +} MBG_SERVICE_SETTINGS_IDX; + + +#define _mbg_swab_svc_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_svc_settings( &(_p)->settings ); \ +} while ( 0 ) + + +typedef enum +{ + MBG_SVC_CAN_BE_DISABLED, + MBG_SVC_CAN_EDIT_CMDLINE, + N_MBG_SVC_FLAGS + +} MBG_SERVICE_INFO_FLAGS; + + +typedef enum +{ + MBG_SVC_MSK_CAN_BE_DISABLED = ( 1UL << MBG_SVC_CAN_BE_DISABLED ), ///< See ::MBG_SVC_CAN_BE_DISABLED + MBG_SVC_MSK_CAN_EDIT_CMDLINE = ( 1UL << MBG_SVC_CAN_EDIT_CMDLINE ) ///< See ::MBG_SVC_CAN_EDIT_CMDLINE + +} MBG_SERVICE_INFO_MSKS; + + +typedef struct +{ + MBG_SERVICE_SETTINGS settings; + uint8_t type; + uint8_t flags; ///< See ::MBG_SERVICE_INFO_MSKS + uint8_t reserved_1[2]; + char name[MBG_SVC_NAME_LEN]; + uint32_t reserved_2[5]; + +} MBG_SERVICE_INFO; + + +#define _mbg_swab_svc_info( _p ) \ +do \ +{ \ + _mbg_swab_svc_settings( &(_p)->settings ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SERVICE_INFO info; + +} MBG_SERVICE_INFO_IDX; + + +#define _mbg_swab_svc_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_svc_info( &(_p)->info ); \ +} while ( 0 ) + + +typedef struct +{ + uint8_t state; ///< See ::MBG_SERVICE_STATE + uint8_t reserved_1[3]; + uint32_t reserved_2[3]; + +} MBG_SERVICE_STATUS; + + +#define _mbg_swab_svc_status( _p ) do {} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_SERVICE_STATUS status; + +} MBG_SERVICE_STATUS_IDX; + + +#define _mbg_swab_svc_status_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_svc_status( &(_p)->status ); \ +} while ( 0 ) + + +/** @} defgroup group_service_mngmnt */ + + + +/** + * @defgroup group_fw_mngmnt Firmware Management + * + * @note These structures and definitions provide extended firmware management + * for Meinberg devices based on Linux / Windows. + * if ::MBG_XFEATURE_FW_MNGMNT is set in the extended device features. + * + * @{ */ + + +enum MBG_FW_GLB_FLAGS +{ + MBG_FW_GLB_FLAG_CAN_SET_OSV, ///< OSV is settable/changeable + N_MBG_FW_GLB_FLAGS +}; + + +enum MBG_FW_GLB_MSKS +{ + MBG_FW_GLB_MSK_CAN_SET_OSV = ( 1UL << MBG_FW_GLB_FLAG_CAN_SET_OSV ) ///< See ::MBG_FW_GLB_FLAG_CAN_SET_OSV +}; + + +typedef struct +{ + uint8_t max_fws; ///< Maximum installable firmwares + uint8_t installed_fws; ///< Currently installed firmwares + uint8_t active_fw; ///< Index of currently active firmware + uint8_t osv_fw; ///< Index of OSV firmware + + uint8_t reserved_1[2]; + uint16_t flags; ///< See ::MBG_FW_GLB_MSKS + + uint32_t reserved_2[14]; + +} MBG_FW_GLB_INFO; + + +#define _mbg_swab_fw_glb_info( _p ) \ +do \ +{ \ +} while ( 0 ) + + +enum MBG_FW_FLAGS +{ + MBG_FW_FLAG_OSV, ///< Originally Shipped Version + MBG_FW_FLAG_ACTIVE, ///< Version is active (currently running) + MBG_FW_FLAG_UNERASABLE, ///< Firmware cannot be erased / deleted (e.g. OSV) + MBG_FW_FLAG_IMMUTABLE, ///< Single files (e.g. UFUs) within firmware cannot be + ///< updated, added, deleted, etc... + N_MBG_FW_FLAGS +}; + + +enum MBG_FW_FLAG_MSKS +{ + MBG_FW_FLAG_MSK_OSV = (1UL << MBG_FW_FLAG_OSV), ///< See ::MBG_FW_FLAG_OSV + MBG_FW_FLAG_MSK_ACTIVE = (1UL << MBG_FW_FLAG_ACTIVE), ///< See ::MBG_FW_FLAG_ACTIVE + MBG_FW_FLAG_MSK_UNERASABLE = (1UL << MBG_FW_FLAG_UNERASABLE), ///< See ::MBG_FW_FLAG_UNERASABLE + MBG_FW_FLAG_MSK_IMMUTABLE = (1UL << MBG_FW_FLAG_IMMUTABLE) ///< See ::MBG_FW_FLAG_IMMUTABLE +}; + + +enum MBG_FW_FILES +{ + MBG_FW_FILE_UNKNOWN, ///< Indicate there are unknown files (older FW scans newer files) + MBG_FW_FILE_INCREMENTAL, ///< Indicate there are incremental update files + MBG_FW_FILE_MEINBERG_DTB, ///< Meinberg device tree describes e.g. front connectors + MBG_FW_FILE_PRELOADER, ///< Whatever preloader magic file + MBG_FW_FILE_ROOTFS, ///< Root filesystem + MBG_FW_FILE_KERNEL_DTB, ///< Kernel device tree + MBG_FW_FILE_RBF, ///< FPGA firmware binary + MBG_FW_FILE_INITRD, ///< Initial ramdisk + MBG_FW_FILE_VERSION_TXT, ///< File containing firmware version + MBG_FW_FILE_KERNEL, ///< Kernel (not necessarily Linux) + N_MBG_FW_FILES +}; + + +#define MBG_FW_FILE_STRS \ +{ \ + "Unknown file(s)", \ + "Incremental file(s)", \ + "Meinberg device tree", \ + "Preloader", \ + "Root filesystem", \ + "Kernel device tree", \ + "FPGA firmware binary", \ + "Initial ramdisk", \ + "Version.txt", \ + "Kernel" \ +} + + +enum MBG_FW_FILE_MSKS +{ + MBG_FW_FILE_MSK_UNKNOWN = (1UL << MBG_FW_FILE_UNKNOWN), ///< See ::MBG_FW_FILE_UNKNOWN + MBG_FW_FILE_MSK_INCREMENTAL = (1UL << MBG_FW_FILE_INCREMENTAL), ///< See ::MBG_FW_FILE_INCREMENTAL + MBG_FW_FILE_MSK_MEINBERG_DTB = (1UL << MBG_FW_FILE_MEINBERG_DTB), ///< See ::MBG_FW_FILE_MEINBERG_DTB + MBG_FW_FILE_MSK_PRELOADER = (1UL << MBG_FW_FILE_PRELOADER), ///< See ::MBG_FW_FILE_PRELOADER + MBG_FW_FILE_MSK_ROOTFS = (1UL << MBG_FW_FILE_ROOTFS), ///< See ::MBG_FW_FILE_ROOTFS + MBG_FW_FILE_MSK_KERNEL_DTB = (1UL << MBG_FW_FILE_KERNEL_DTB), ///< See ::MBG_FW_FILE_KERNEL_DTB + MBG_FW_FILE_MSK_RBF = (1UL << MBG_FW_FILE_RBF), ///< See ::MBG_FW_FILE_RBF + MBG_FW_FILE_MSK_INITRD = (1UL << MBG_FW_FILE_INITRD), ///< See ::MBG_FW_FILE_INITRD + MBG_FW_FILE_MSK_VERSION_TXT = (1UL << MBG_FW_FILE_VERSION_TXT), ///< See ::MBG_FW_FILE_VERSION_TXT + MBG_FW_FILE_MSK_KERNEL = (1UL << MBG_FW_FILE_KERNEL) ///< See ::MBG_FW_FILE_KERNEL +}; + + +typedef struct +{ + uint32_t revision; ///< Main revision information + uint32_t flags; ///< See ::MBG_FW_FLAG_MSKS + uint16_t num_ufus; ///< Number of available UFUs + uint16_t reserved_1; + uint8_t release_candidate; ///< Release candidate revision information + uint8_t reserved_2[3]; + uint32_t files; ///< Single file (list) flags, See ::MBG_FW_FILE_MSKS + uint32_t reserved_3[11]; + +} MBG_FW_INFO; + + +#define _mbg_swab_fw_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->revision ); \ + _mbg_swab32( &(_p)->flags ); \ + _mbg_swab16( &(_p)->num_ufus ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_FW_INFO info; + +} MBG_FW_INFO_IDX; + + +#define _mbg_swab_fw_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_fw_info( &(_p)->info ); \ +} while ( 0 ) + + +typedef struct +{ + uint32_t revision; ///< Main revision information + uint8_t release_candidate; ///< Release candidate revision information + uint8_t reserved_1[3]; + uint16_t model_code; ///< One of ::GPS_MODEL_CODES + uint16_t reserved_2; + uint32_t reserved_3[5]; + +} MBG_FW_UFU_INFO; + + +#define _mbg_swab_fw_ufu_info( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->revision ); \ + _mbg_swab16( &(_p)->model_code ); \ +} while ( 0 ) + + +typedef struct +{ + uint16_t fw_idx; ///< 0...::MBG_FW_GLB_INFO::installed_fws - 1 + uint16_t ufu_idx; ///< 0...::MBG_FW_INFO::num_ufus-1 + MBG_FW_UFU_INFO info; ///< See ::MBG_FW_UFU_INFO + +} MBG_FW_UFU_INFO_IDX; + + +#define _mbg_swab_fw_ufu_info_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->fw_idx ); \ + _mbg_swab16( &(_p)->ufu_idx ); \ + _mbg_swab_fw_ufu_info( &(_p)->info ); \ +} while ( 0 ) + + +/** + * @brief Command types used to flash UFU(S) to device(s) + */ +enum MBG_FW_UFU_FLASH_CMDS +{ + /// ::MBG_FW_UFU_FLASH_CMD::ufu_idx and ::MBG_FW_UFU_FLASH_CMD::xbp_addr must be set. + /// Send one specific UFU to a specific device identified by its XBP address + MBG_FW_UFU_FLASH_CMD_DEVICE_UFU, + + /// ::MBG_FW_UFU_FLASH_CMD::ufu_idx must be set. + /// Send one specific UFU to all suitable devices that fit the model code. + MBG_FW_UFU_FLASH_CMD_UFU_ALL, + + /// ::MBG_FW_UFU_FLASH_CMD::xbp_addr must be set. + /// Find the newest firmware version for a device identified by its XBP address + /// and flash it. + MBG_FW_UFU_FLASH_CMD_DEVICE, + + /// ::MBG_FW_UFU_FLASH_CMD::model_code must be set. + /// Find the newest firmware version for specific devices identified by + /// the model code of the firmware, and flash that firmware to all suitable devices. + MBG_FW_UFU_FLASH_CMD_TYPE, + + /// Find the newest firmware version for each single device and flash + /// each device with a corresponding firmware. + MBG_FW_UFU_FLASH_CMD_ALL, + + N_MBG_FW_UFU_FLASH_CMDS +}; + + +/** + * @brief Data used with UFU firmware flash command. + * + * @note Please note that, depending on the command, specific members in + * ::MBG_FW_UFU_FLASH_CMD are valid, all others should be zero and be ignored. + */ +typedef struct +{ + uint8_t cmd; ///< See ::MBG_FW_UFU_FLASH_CMDS + uint8_t reserved_1; ///< Future use + uint16_t ufu_idx; ///< See ::MBG_FW_UFU_FLASH_CMD_DEVICE_UFU + XBP_ADDR xbp_addr; ///< See ::MBG_FW_UFU_FLASH_CMD_DEVICE_UFU or + ///< ::MBG_FW_UFU_FLASH_CMD_DEVICE + uint16_t model_code; ///< See ::MBG_FW_UFU_FLASH_CMD_TYPE + uint16_t reserved_3; ///< Future use + uint32_t reserved_4[4]; ///< Future use + +} MBG_FW_UFU_FLASH_CMD; + + +#define _mbg_swab_fw_ufu_flash_cmd( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->ufu_idx ); \ + _mbg_swab16( &(_p)->model_code ); \ +} while ( 0 ) + + +/** @} defgroup group_fw_mngmnt */ + + + +/** + * @defgroup group_database Database(s) + * + * @note These structures and definitions provide database functionality + * if ::MBG_XFEATURE_DATABASE is set in the extended device features. + * + * @{ */ + + +enum MBG_DATABASE_TYPES +{ + MBG_DATABASE_TYPE_SQLITE, ///< SQLite + MBG_DATABASE_TYPE_MYSQL, ///< MySQL + MBG_DATABASE_TYPE_POSTGRESQL, ///< PostgreSQL + N_MBG_DATABASE_TYPES +}; + + +#define MBG_DATABASE_TYPE_STRS \ +{ \ + "SQLite", \ + "MySQL", \ + "PostgreSQL" \ +} + + +typedef struct +{ + uint8_t num_dbs; ///< Number of configurable databases + uint8_t reserved_1; + uint16_t reserved_2; + uint32_t reserved_3[3]; + +} MBG_DATABASE_GLB_INFO; + + +#define _mbg_swab_database_glb_info( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->supp_dbs ); \ +} while ( 0 ) + + +enum MBG_DATABASE_SETTINGS_FLAGS +{ + MBG_DATABASE_SETTINGS_FLAG_ENABLE, ///< Enable, disable logging to database + MBG_DATABASE_SETTINGS_FLAG_SAVE_PERSIST, ///< Save database (cyclically) to a persistent storage + N_MBG_DATABASE_SETTINGS_FLAGS +}; + + +enum MBG_DATABASE_SETTINGS_FLAG_MSKS +{ + MBG_DATABASE_SETTINGS_FLAG_MSK_ENABLE = (1UL << MBG_DATABASE_SETTINGS_FLAG_ENABLE), ///< See ::MBG_DATABASE_SETTINGS_FLAG_ENABLE + MBG_DATABASE_SETTINGS_FLAG_MSK_SAVE_PERSIST = (1UL << MBG_DATABASE_SETTINGS_FLAG_SAVE_PERSIST) ///< See ::MBG_DATABASE_SETTINGS_FLAG_SAVE_PERSIST +}; + + +#define MBG_DATABASE_MAX_STR 32 + + +typedef struct +{ + uint16_t flags; ///< See ::MBG_DATABASE_SETTINGS_FLAG_MSKS. + uint16_t port; ///< Remote host port. + uint32_t reserved_2[7]; + char user[MBG_DATABASE_MAX_STR]; ///< Database username. + char password[MBG_DATABASE_MAX_STR]; ///< Database password. + + /// @brief Database host. + /// + /// Can be set to a remote database server (MySQL, PostgreSQL, etc.) + /// or even to a local file path in case of a SQLite database. + /// In case of a local file database, ::MBG_DATABASE_INFO_FLAG_MSK_LOCAL_FILE + /// should be set in ::MBG_DATABASE_INFO::flags to announce its path, + /// so a capable piece of software can fetch it via the TLV API. + char host[MBG_MAX_HOSTNAME_LEN]; + + char dbname[MBG_DATABASE_MAX_STR]; ///< Database name. + char reserved_3[MBG_DATABASE_MAX_STR]; + char reserved_4[MBG_DATABASE_MAX_STR]; + +} MBG_DATABASE_SETTINGS; + + +#define _mbg_swab_database_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->port ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_DATABASE_SETTINGS settings; + +} MBG_DATABASE_SETTINGS_IDX; + + +#define _mbg_swab_database_settings_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_database_settings( &(_p)->settings ); \ +} while ( 0 ) + + +enum MBG_DATABASE_INFO_FLAGS +{ + MBG_DATABASE_INFO_FLAG_LOCAL_FILE, ///< Database is a local file only + N_MBG_DATABASE_INFO_FLAGS +}; + + +enum MBG_DATABASE_INFO_FLAG_MSKS +{ + /// @brief See ::MBG_DATABASE_INFO_FLAG_LOCAL_FILE + MBG_DATABASE_INFO_FLAG_MSK_LOCAL_FILE = ( 1UL << MBG_DATABASE_INFO_FLAG_LOCAL_FILE ) +}; + + +enum MBG_DATABASE_MEMBERS +{ + MBG_DATABASE_MEMBER_FLAGS, ///< ::MBG_DATABASE_SETTINGS::flags is valid + MBG_DATABASE_MEMBER_PORT, ///< ::MBG_DATABASE_SETTINGS::port is valid + MBG_DATABASE_MEMBER_USER, ///< ::MBG_DATABASE_SETTINGS::user is valid + MBG_DATABASE_MEMBER_PASSWORD, ///< ::MBG_DATABASE_SETTINGS::password is valid + MBG_DATABASE_MEMBER_HOST, ///< ::MBG_DATABASE_SETTINGS::host is valid + MBG_DATABASE_MEMBER_DBNAME, ///< ::MBG_DATABASE_SETTINGS::dbname is valid + N_MBG_DATABASE_MEMBERS +}; + + +enum MBG_DATABASE_MEMBER_MSKS +{ + MBG_DATABASE_MEMBER_MSK_FLAGS = (1UL << MBG_DATABASE_MEMBER_FLAGS), ///< See ::MBG_DATABASE_MEMBER_FLAGS + MBG_DATABASE_MEMBER_MSK_PORT = (1UL << MBG_DATABASE_MEMBER_PORT), ///< See ::MBG_DATABASE_MEMBER_PORT + MBG_DATABASE_MEMBER_MSK_USER = (1UL << MBG_DATABASE_MEMBER_USER), ///< See ::MBG_DATABASE_MEMBER_USER + MBG_DATABASE_MEMBER_MSK_PASSWORD = (1UL << MBG_DATABASE_MEMBER_PASSWORD), ///< See ::MBG_DATABASE_MEMBER_PASSWORD + MBG_DATABASE_MEMBER_MSK_HOST = (1UL << MBG_DATABASE_MEMBER_HOST), ///< See ::MBG_DATABASE_MEMBER_HOST + MBG_DATABASE_MEMBER_MSK_DBNAME = (1UL << MBG_DATABASE_MEMBER_DBNAME) ///< See ::MBG_DATABASE_MEMBER_DBNAME +}; + + +typedef struct +{ + MBG_DATABASE_SETTINGS settings; ///< See ::MBG_DATABASE_SETTINGS + uint8_t type; ///< See ::MBG_DATABASE_TYPES + uint8_t flags; ///< See ::MBG_DATABASE_INFO_FLAG_MSKS + + /// @brief Flag field indicating which ::MBG_DATABASE_MEMBER_MSKS are valid. + uint16_t supp_members; + + /// @brief Flag field which ::MBG_DATABASE_MEMBER_MSKS are configurable. + /// + /// Subset of ::MBG_DATABASE_INFO::supp_members. + uint16_t supp_cfgs; + + /// @brief Supported settings flags. + /// + /// If ::MBG_DATABASE_MEMBER_MSK_FLAGS is set in ::MBG_DATABASE_INFO::supp_members + /// and ::MBG_DATABASE_MEMBER_MSK_FLAGS is set in ::MBG_DATABASE_INFO::supp_cfgs, + /// this is the flag field of supported ::MBG_DATABASE_SETTINGS_FLAG_MSKS in + /// ::MBG_DATABASE_SETTINGS::flags. + uint16_t supp_settings_flags; + + uint32_t reserved_3[2]; + +} MBG_DATABASE_INFO; + + +#define _mbg_swab_database_info( _p ) \ +do \ +{ \ + _mbg_swab_database_settings( &(_p)->settings ); \ + _mbg_swab16( &(_p)->supp_members ); \ + _mbg_swab16( &(_p)->supp_cfgs ); \ +} while ( 0 ) + + +typedef struct +{ + MBG_MSG_IDX_32 idx; + MBG_DATABASE_INFO info; + +} MBG_DATABASE_INFO_IDX; + + +#define _mbg_swab_database_info_idx( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->idx ); \ + _mbg_swab_database_info( &(_p)->info ); \ +} while ( 0 ) + + +enum MBG_DATABASE_CMDS +{ + MBG_DATABASE_CMD_RESET_SV_LOGS, + N_MBG_DATABASE_CMDS +}; + + +typedef struct +{ + uint32_t cmd; ///< See ::MBG_DATABASE_CMDS + uint32_t length; ///< Payload data length of ::MBG_DATABASE_CMD::payload + uint32_t reserved[2]; ///< Future use + unsigned char payload[240]; ///< Payload data + +} MBG_DATABASE_CMD; + + +#define _mbg_swab_database_cmd( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->cmd ); \ + _mbg_swab32( &(_p)->length ); \ +} while ( 0 ) + + +/** @} defgroup group_database */ + + + +/** + * @defgroup group_fcu_api FCU API + * + * @note These structures and definitions allow configuration + * and status monitoring of multiple power supplies and fans. + * Only supported if ::MBG_XFEATURE_FCU_API is set. + * The legacy device FCU_01 does ***not*** support this API. + * + * @{ */ + + +/** + * @brief The maximum number of power supply modules supported by the API. + * + * This is limited e.g. by the number of bits available + * in ::MBG_FCU_SETTINGS::installed_power_supplies. + * Existing FCU modules normally only support a much smaller + * number of power supplies. + */ +#define FCU_MAX_PSU_MODULES 16 +// NOTE Changing the numeric value breaks API compatibility. + + +/** + * @brief The maximum number of fan control modules supported by the API. + * + * This is limited e.g. by the number of bits available + * in ::MBG_FCU_SETTINGS::fan_units_to_disable. + * The number of fan modules supported by a particular FCU module + * is usually smaller. + */ +#define FCU_MAX_FAN_MODULES 16 +// NOTE Changing the numeric value breaks API compatibility. + + +/** + * @brief The maximum number of fan control lines per fan module. + * + * This is an arbitrary maximum number. + * Existing FCU modules normally only support a much smaller + * number of fan modules, e.g. 1 or 4, depending on the fan + * module hardware and the FCU model. + */ +#define FCU_MAX_FANS_CTRL_PER_MODULE 8 +// NOTE Changing the numeric value breaks API compatibility. + + + +/** + * @brief Configuration settings to be sent to an FCU module. + */ +typedef struct +{ + /// @brief Bit mask used to tell the FCU module which slot(s) + /// are known to have a power supply module is physically installed. + /// + /// This tells the FCU that power should be available from those slots, + /// and thus affects the status reported for a power supply slot, + /// i.e. "not available" vs. "OK" or "faulty". + uint16_t installed_power_supplies; + + /// @brief Bit mask of fan modules to be ***disabled*** by the FCU. + /// + /// By default, all fan modules are anyway enabled after + /// power-up, so the control program can explicitly disable + /// selected modules later, if preferred for some reason. + uint16_t fan_units_to_disable; + + uint16_t reserved_0; ///< Currently not used, should be set to 0. + uint16_t reserved_1; ///< Currently not used, should be set to 0. + + uint16_t reserved_2; ///< Currently not used, should be set to 0. + uint16_t reserved_3; ///< Currently not used, should be set to 0. + uint16_t reserved_4; ///< Currently not used, should be set to 0. + uint16_t reserved_5; ///< Currently not used, should be set to 0. + +} MBG_FCU_SETTINGS; + +#define _mbg_swab_fcu_settings( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->installed_power_supplies ); \ + _mbg_swab16( &(_p)->fan_units_to_disable ); \ + _mbg_swab16( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ + _mbg_swab16( &(_p)->reserved_2 ); \ + _mbg_swab16( &(_p)->reserved_3 ); \ + _mbg_swab16( &(_p)->reserved_4 ); \ + _mbg_swab16( &(_p)->reserved_5 ); \ +} while ( 0 ) + + + +/** + * @brief Info and current settings to be retrieved from an FCU module. + */ +typedef struct +{ + MBG_FCU_SETTINGS fcu_settings; ///< Current settings. + + /// @brief The number of power supply modules that can be + /// monitored by the particular FCU module. + /// + /// Must not exceed ::FCU_MAX_PSU_MODULES. + uint8_t n_psu_modules; + + /// @brief The number of fan modules that can be monitored + /// by the particular FCU module. + /// + /// Must no exceed ::FCU_MAX_FAN_MODULES. + uint8_t n_fan_modules; + + uint8_t reserved_0; ///< Currently not used, reserved. + uint8_t reserved_1; ///< Currently not used, reserved. + + uint32_t reserved_2; ///< Currently not used, reserved. + + /// @brief The number of fan control lines for each fan module. + /// + /// Some module types may have 1 fan with 1 control line, + /// there may be modules with several fans, each of which + /// has its own control line, and finally there may be modules + /// with several fans that share a single summary control line. + /// The FCU firmware can determine and report these values + /// depending on the hardware it is running on. + uint8_t fan_ctrls_per_module[FCU_MAX_FAN_MODULES]; + + uint32_t reserved_3; ///< Currently not used, reserved. + uint32_t reserved_4; ///< Currently not used, reserved. + uint32_t reserved_5; ///< Currently not used, reserved. + uint32_t reserved_6; ///< Currently not used, reserved. + +} MBG_FCU_INFO; + +#define _mbg_swab_fcu_info( _p ) \ +do \ +{ \ + _mbg_swab_fcu_settings( &(_p)->fcu_settings ); \ + _mbg_swab8( &(_p)->n_psu_modules ); \ + _mbg_swab8( &(_p)->n_fan_modules ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab8( &(_p)->reserved_1 ); \ + _mbg_swab32( &(_p)->reserved_2 ); \ + _mbg_swab32( &(_p)->reserved_3 ); \ + _mbg_swab32( &(_p)->reserved_4 ); \ + _mbg_swab32( &(_p)->reserved_5 ); \ + _mbg_swab32( &(_p)->reserved_6 ); \ +} while ( 0 ) + + + +/** + * @brief Power supply status information to be retrieved from an FCU module. + * + * ::MBG_FCU_INFO::n_psu_modules are supported by the FCU module, + * but how many and which power supply modules are actually + * monitored depends on the bit mask ::MBG_FCU_SETTINGS::installed_power_supplies + * that has been sent to the FCU module. + */ +typedef struct +{ + uint8_t status; ///< The status, see ::FCU_PSU_STAT_CODES. + uint8_t reserved_0; ///< Currently unused, reserved. + uint16_t reserved_1; ///< Currently unused, reserved. + +} MBG_FCU_PSU_STAT; + +#define _mbg_swab_fcu_psu_stat( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->status ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Power supply status codes used with ::MBG_FCU_PSU_STAT::status. + */ +enum FCU_PSU_STAT_CODES +{ + /// The bit mask in ::MBG_FCU_SETTINGS::installed_power_supplies + /// indicates there is no PSU module expected in this slot, and + /// the associated voltage sense line is low, es expected. + FCU_PSU_STAT_CODE_NOT_AVAIL, + + /// The bit mask in ::MBG_FCU_SETTINGS::installed_power_supplies + /// indicates there is no PSU module expected in this slot, but + /// the associated voltage sense line is anyway high, so obviously + /// a PSU module is installed which has not yet been registered. + FCU_PSU_STAT_CODE_UNREGISTERED, + + /// The bit mask in ::MBG_FCU_SETTINGS::installed_power_supplies + /// indicates there is a PSU module installed in this slot, and + /// the associated voltage sense line is high, so the PSU works + /// properly. + FCU_PSU_STAT_CODE_OK, + + /// The bit mask in ::MBG_FCU_SETTINGS::installed_power_supplies + /// indicates there is a PSU module installed in this slot, but + /// the associated voltage sense line is low, so the PSU is faulty + /// or has been removed. + FCU_PSU_STAT_CODE_FAIL, + + N_FCU_PSU_STAT_CODE ///< The number of known status codes. +}; + + + +/** + * @brief Power supply status information plus module index. + * + * Monitoring software should poll index 0...::MBG_FCU_INFO::n_psu_modules-1. + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0...::MBG_FCU_INFO::n_psu_modules-1. + MBG_FCU_PSU_STAT psu_stat; + +} MBG_FCU_PSU_STAT_IDX; + +#define _mbg_swab_fcu_psu_stat_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_fcu_psu_stat( &(_p)->psu_stat ); \ +} while ( 0 ) + + + +/** + * @brief Fan status information to be retrieved from an FCU module. + * + * ::MBG_FCU_INFO::n_fan_modules are supported by the FCU module, + * but how many fan modules with one or more control lines each + * are actually monitored depends on the FCU device and fan hardware. + */ +typedef struct +{ + /// @brief Indicates how many control lines are checked + /// + /// for the specified module, i.e. how many items + /// of @a #status contain relevant status information. + /// Should correspond to ::MBG_FCU_INFO::fan_ctrls_per_module. + uint8_t n_ctrls; + + uint8_t reserved_0; ///< Currently unused, reserved. + uint16_t reserved_1; ///< Currently unused, reserved. + + uint8_t status[FCU_MAX_FANS_CTRL_PER_MODULE]; ///< See ::FCU_FAN_STAT_CODES. + +} MBG_FCU_FAN_STAT; + +#define _mbg_swab_fcu_fan_stat( _p ) \ +do \ +{ \ + _mbg_swab8( &(_p)->n_ctrls ); \ + _mbg_swab8( &(_p)->reserved_0 ); \ + _mbg_swab16( &(_p)->reserved_1 ); \ +} while ( 0 ) + + + +/** + * @brief Fan status codes used with ::MBG_FCU_FAN_STAT::status. + */ +enum FCU_FAN_STAT_CODES +{ + FCU_FAN_STAT_CODE_NOT_AVAIL, ///< No fan installed at the control line of this unit. + FCU_FAN_STAT_CODE_DISABLED, ///< Fan installed but disabled. + FCU_FAN_STAT_CODE_OK, ///< Fan installed and working OK. + FCU_FAN_STAT_CODE_TURNED_OFF, ///< Fan turned off by frontpanel switch. + FCU_FAN_STAT_CODE_FAULTY, ///< Fan installed but fails. + N_FCU_FAN_STAT_CODE ///< The number of known status codes. +}; + + + +/** + * @brief Fan status information plus module index. + * + * Monitoring software should poll index 0...::MBG_FCU_INFO::n_fan_modules-1. + */ +typedef struct +{ + MBG_MSG_IDX idx; ///< 0...::MBG_FCU_INFO::n_fan_modules-1. + MBG_FCU_FAN_STAT fan_stat; + +} MBG_FCU_FAN_STAT_IDX; + +#define _mbg_swab_fcu_fan_stat_idx( _p ) \ +do \ +{ \ + _mbg_swab16( &(_p)->idx ); \ + _mbg_swab_fcu_fan_stat( &(_p)->fan_stat ); \ +} while ( 0 ) + + +/** @} defgroup group_fcu_api */ + + + #if defined( _USING_BYTE_ALIGNMENT ) #pragma pack() // set default alignment #undef _USING_BYTE_ALIGNMENT diff --git a/c/mbglib/include/gpsserio.h b/c/mbglib/include/gpsserio.h deleted file mode 100644 index 5971d12..0000000 --- a/c/mbglib/include/gpsserio.h +++ /dev/null @@ -1,982 +0,0 @@ - -/************************************************************************** - * - * $Id: gpsserio.h 1.40.1.1 2012/06/15 07:58:42Z martin TEST $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for gpsserio.c. - * - * This file defines structures and codes to be used to access - * Meinberg GPS clocks via their serial interface COM0. COM0 should - * be set to a high baud rate, default is 19200. - * - * Standard Meinberg GPS serial operation is to send the Meinberg - * standard time string automatically once per second, once per - * minute, or on request per ASCII '?'. - * - * GPS parameter setup or parameter readout uses blocks of binary - * data which have to be isolated from the standard string. A block - * of data starts with a SOH code (ASCII Start Of Header, 0x01) - * followed by a message header with constant length and a block of - * data with variable length. - * - * The first field (cmd) of the message header holds the command - * code rsp. the type of data to be transmitted. The next field (len) - * gives the number of data bytes that follow the header. This number - * ranges from 0 to sizeof( MSG_DATA ). The third field (data_csum) - * holds a checksum of all data bytes and the last field of the header - * finally holds the checksum of the header itself. - * - * ----------------------------------------------------------------------- - * $Log: gpsserio.h $ - * Revision 1.40.1.1 2012/06/15 07:58:42Z martin - * Preliminary support for NACK received status. - * Revision 1.40 2012/04/11 16:03:29 martin - * Fixed some doxygen stuff. - * Revision 1.39 2012/03/08 15:34:18Z martin - * Added default setting for _USE_USB_IO. - * Revision 1.38 2012/03/06 15:33:43 martin - * Added support for SCU and LNO. - * Account for modified chk_tstr() parameters. - * Revision 1.37 2011/11/25 14:59:17Z martin - * Account for some renamed evt_log library symbols. - * Revision 1.36 2011/11/25 10:37:10 martin - * Added commands and data structures to support log events. - * Revision 1.35 2011/07/29 09:46:54 daniel - * Use native alignment only. - * Added command code GPS_XMR_INSTANCES. - * Support GPIO configuration. - * Support for USB. - * Revision 1.34 2011/04/15 13:12:02 martin - * Added initializer for command name table. - * Unified mutex stuff using macros from mbgmutex.h. - * Revision 1.33 2010/09/07 07:18:08 daniel - * New codes and structures for multi GNSS support. - * Defines to support reading raw IRIG data. - * Revision 1.32 2009/08/26 09:02:21 daniel - * Added new commands GPS_NAV_ENG_SETTINGS and - * GPS_GLNS_ALM. - * Revision 1.31 2009/08/24 13:32:33Z martin - * Renamed symbol MBGEXTIO_TIMEOUT_SOCKET to MBGEXTIO_RCV_TIMEOUT_SOCKET. - * Support new timeout handling distinguishing between character timeout - * and message timeout. Timeout values are now expected in milliseconds. - * Revision 1.30 2009/07/02 09:19:31 martin - * Moved definitions related to LAN interface configuration to gpsdefs.h. - * Revision 1.29 2009/03/10 17:00:29 martin - * Support configurable time scales. - * Don't pack structure MBG_MSG_CTL but use default alignment. - * Revision 1.28 2008/09/04 12:47:10Z martin - * Moved generic serial I/O stuff to mbgserio.h. - * Preliminarily support chk_tstr. - * Revision 1.27 2008/04/07 10:49:13Z martin - * Added cmd GPS_CLR_UCAP_BUFF. - * Revision 1.26 2007/02/27 09:51:45 martin - * Modified mutex macros for Windows. - * Added type TZCODE which is used by the binary protocol but - * has a different size than PCPS_TZCODE. - * Now _USE_PCPSDEFS by default for non-firmware apps. - * Fixed comments on GPS_OPT_SETTINGS and GPS_OPT_INFO. - * Revision 1.25 2007/02/06 16:31:04Z martin - * Modified comment for PZF_PCPS_TIME which can now also - * be sent to a device. - * Added mutex support. - * Added SVNO to the buffer union. - * Added support for OPT_SETTINGS. - * Added XMULTI_REF_... definitions. - * Modified some comments. - * Revision 1.24 2006/12/21 10:54:14Z martin - * Moved macro _IS_MBG_FIRMWARE to words.h. - * Cleaned up definitions of default I/O macros. - * Revision 1.23 2006/12/12 15:53:58 martin - * Added structure LAN_IF_INFO and associated codes. - * Added cmd codes GPS_IRIG_RX_SETTINGS and GPS_IRIG_RX_INFO. - * Added new member irig_rx_info to union MSG_DATA. - * Added cmd code GPS_REF_OFFS and associated definitions. - * Added cmd code GPS_DEBUG_STATUS. - * Define MBG_HANDLE for DOS even without v24tools. - * Revision 1.22 2006/11/02 08:57:56 martin - * Added a typedef to avoid firmware build errors. - * Revision 1.21 2006/10/25 12:25:35Z martin - * Support serial I/O under Windows. - * Removed obsolete definitions. - * Updated function prototypes. - * Revision 1.20 2006/08/24 13:00:08Z martin - * Added conditional support for network socket I/O and encrypted packets. - * Serial I/O is now also conditional only. - * Added/renamed/redefined structures as required. - * Revision 1.19 2006/06/15 10:39:49Z martin - * Added some special types to the MSG_DATA union which have - * previously been defined as generic uint16_t types. - * Removed MBG_OPT_SETTINGS and MBG_OPT_INFO from - * the MSG_DATA union since those types are not used with - * the binary protocol. - * Revision 1.18 2006/05/18 09:43:35Z martin - * New cmd code GPS_IGNORE_LOCK. - * Added command codes for PZF receivers. - * Renamed IRIG_... symbols to IRIG_TX_... in order to distinguish - * from IRIG input configuration which might be available in the future. - * Added some fields to the MSG_DATA union. - * Renamed MSG_BUFF field "data" to "msg_data" in order to avoid - * conflict with reserved word in some environments. - * Rewrote inclusion control macros. - * Replace control of inclusion of function prototypes by new symbol - * _USE_GPSSERIO_FNC which can be fully overridden. - * Updated lots of comments. - * Revision 1.17 2005/09/08 14:47:05Z martin - * Changed type of MSG_RCV_CTL::flags from int to ulong - * to avoid compiler warnings. - * Revision 1.16 2005/04/26 10:53:53Z martin - * Updated function prototypes. - * Revision 1.15 2004/12/28 11:02:20Z martin - * Redefined interface data types using C99 fixed-size definitions. - * Replaced received_header by flags in MSG_RCV_CTL. - * Defined flag bits and corresponding bit masks. - * Updated function prototypes. - * Revision 1.14 2004/07/08 08:28:30 martin - * New cmd code GPS_RCV_TIMEOUT which is only supported if - * feature mask GPS_HAS_RCV_TIMEOUT is set. - * Revision 1.13 2004/06/16 14:13:50 martin - * Changed name of symbol which controls inclusion of function prototypes. - * Don't include function prototypes by default if compiling firmware. - * Conditionally support private data structures, automatically include - * those definitions if compiling firmware. - * The data portion of MSG_BUFF is now a union whose maximum size - * can be overridden by a preprocessor value. - * Added MBG_OPT_SETTINGS and MBG_OPT_INFO to the buffer union. - * Updated function prototypes. - * Revision 1.12 2004/04/16 09:16:00Z andre - * Added command code GPS_MULTI_REF_STATUS. - * Revision 1.11 2004/03/26 11:08:28Z martin - * Compile function prototypes conditionally only. - * if symbol _INCL_GPSSERIO_FNC is defined. - * New structure MSG_RCV_CTL to support binary - * protocol on several ports. - * Added support for IPv4 LAN interface configuration. - * Support MULTI_REF_SETTINGS/MULTI_REF_INFO. - * Added command code to query ROM checksum. - * Modified some comments. - * Updated function prototypes. - * Revision 1.10 2002/08/21 07:39:32Z werner - * POUT_PROG -> POUT_INFO - * Revision 1.9 2002/01/29 15:29:16Z MARTIN - * Renamed cmd code GPS_IRIG_CFG to GPS_IRIG_SETTINGS. - * Added new cmd codes GPS_RECEIVER_INFO...GPS_IRIG_INFO - * and updated msg buffer union with corresponding fields. - * Removed obsolete types OPT_FEATURES, IRIG_CFG and - * associated definitions. - * Modified some comments. - * Revision 1.8 2001/04/06 11:51:24 Andre - * transfercodes and structures for IRIG parameter and installed - * options added - * Revision 1.7 2001/03/30 10:47:04Z MARTIN - * New file header. - * Control alignment of structures from new file use_pack.h. - * Modified syntax and some comments. - * - **************************************************************************/ - -#ifndef _GPSSERIO_H -#define _GPSSERIO_H - - -/* Other headers to be included */ - -#include <gpsdefs.h> -#include <use_pack.h> - - -/* - * The following macros control parts of the build process. - * The default values are suitable for most cases but can be - * overridden by global definitions, if required. - */ - -#if _IS_MBG_FIRMWARE - // This handle type in not used by the firmware. - // However, we define it to avoid build errors. - typedef int MBG_HANDLE; - -#endif - - -#ifndef _USE_MUTEX - #if defined( MBG_TGT_WIN32 ) - #define _USE_MUTEX 1 - #elif defined( MBG_TGT_UNIX ) - #define _USE_MUTEX 1 - #endif -#endif - -#ifndef _USE_MUTEX - #define _USE_MUTEX 0 // not used by default -#endif - - -/* Control whether network socket communication shall be supported */ -#ifndef _USE_SOCKET_IO - #define _USE_SOCKET_IO 0 // not supported by default -#endif - -/* Control whether serial port communication shall be supported */ -#ifndef _USE_SERIAL_IO - #if _IS_MBG_FIRMWARE - #define _USE_SERIAL_IO 0 // Firmware provides its own serial I/O functions - #else - #define _USE_SERIAL_IO 1 // supported by default - #endif -#endif - -/* Control whether USB communication shall be supported */ -#if defined( MBG_TGT_LINUX ) - #ifndef _USE_USB_IO // may be overridden by project settings - #define _USE_USB_IO 0 // not supported by default - #endif -#else - // USB I/O requires libusb and is currently only supported under Linux. - // So for non-Linux targets force _USE_USB_IO to 0. - #define _USE_USB_IO 0 // not supported by default -#endif - - -/* Control inclusion of secudefs.h */ -#if _USE_SOCKET_IO - // Network socket I/O always requires secudefs, so make sure - // this is defined correctly. - #ifdef _USE_ENCRYPTION - #undef _USE_ENCRYPTION - #endif - #define _USE_ENCRYPTION 1 -#else - // If no socket I/O is used then secudefs aren't required, either. - #ifndef _USE_ENCRYPTION - #define _USE_ENCRYPTION 0 - #endif -#endif - -/* Control inclusion of pcpsdefs.h */ -#ifndef _USE_PCPSDEFS - #if _IS_MBG_FIRMWARE - // for firmware depend on the target system - #if defined( _CC51 ) - #define _USE_PCPSDEFS 1 - #else - #define _USE_PCPSDEFS 0 - #endif - #else - // otherwise include it by default - #define _USE_PCPSDEFS 1 - #endif -#endif - -/* Control inclusion of non-public declarations */ -#ifndef _USE_GPSPRIV - /* by default do include if building a GPS firmware */ - #define _USE_GPSPRIV _IS_MBG_FIRMWARE -#endif - -/* Control inclusion of function prototypes */ -#ifndef _USE_GPSSERIO_FNC - /* by default don't include if building a firmware */ - #define _USE_GPSSERIO_FNC ( !_IS_MBG_FIRMWARE ) -#endif - -#ifndef _USE_RCV_TSTAMP - #define _USE_RCV_TSTAMP ( !_IS_MBG_FIRMWARE ) -#endif - - -#if _USE_MUTEX - #include <mbgmutex.h> -#endif - -#if _USE_SERIAL_IO - #include <mbgserio.h> -#endif - -#if _USE_USB_IO - #include <mbgusbio.h> -#endif - -#if _USE_SOCKET_IO - #if defined( MBG_TGT_UNIX ) - #include <netdb.h> - #endif -#endif - -#if _USE_ENCRYPTION - #include <secudefs.h> - #include <aes128.h> -#endif - -#if _USE_PCPSDEFS - #include <pcpsdefs.h> -#endif - -#if _USE_GPSPRIV - #include <gpspriv.h> -#endif - -#if _USE_RCV_TSTAMP - #include <mbg_tmo.h> -#endif - - -#ifdef __cplusplus -extern "C" { -#endif - -#ifdef _GPSSERIO - #define _ext -#else - #define _ext extern -#endif - - -/* Start of header body */ - -// We don't use pragma pack() here but native alignment. - - -/* Status codes of check_transfer() function. */ - -#define TR_COMPLETE 2 -#define TR_RECEIVING 1 -#define TR_WAITING 0 -#define TR_TIMEOUT -1 -#define TR_CSUM_HDR -2 -#define TR_CSUM_DATA -3 -#define TR_DECRYPTION -4 -#define TR_OPEN_ERR -5 -#define TR_IO_ERR -6 -#define TR_AUTH_ERR -7 -#define TR_RCVD_NACK -8 - - -/* The code below is sent before a message header. */ - -#define START_OF_HEADER 0x01 /* ASCII SOH */ - - -/* The control codes defined below are to be or'ed with a command/type code. */ - -#define GPS_REQACK 0x8000 /* to GPS rcvr: request acknowledge */ -#define GPS_ACK 0x4000 /* from GPS rcvr: acknowledge a command */ -#define GPS_NACK 0x2000 /* from GPS rcvr: error receiving command */ - -#define GPS_CTRL_MSK 0xF000 /* masks control code from command */ - - -/**< @defgroup group_gps_cmds_serial GPS commands passed via serial port - * - * These codes specify commands/types of data to be supplied to - * the GPS receiver: - */ -/* clock auto-message to host */ -/* | host request, clock response */ -/* | | host download to clock */ -/* | | | */ -enum /* | | | */ -{ /* system data */ - GPS_AUTO_ON = 0x000, /* | | | X | no param, enable auto-msgs from GPS rcvr */ - GPS_AUTO_OFF, /* | | | X | no param, disable auto-msgs from GPS rcvr */ - GPS_SW_REV, /* | | X | | SW_REV, software revision */ - GPS_BVAR_STAT, /* | | X | | BVAR_STAT, status of buffered variables */ - GPS_TIME, /* | X | | X | TTM, current time or capture, or init board time */ - GPS_POS_XYZ, /* | | X | X | XYZ, current position in ECEF coords */ - GPS_POS_LLA, /* | | X | X | LLA, current position in geographic coords */ - GPS_TZDL, /* | | X | X | TZDL, time zone / daylight saving */ - GPS_PORT_PARM, /* | | X | X | PORT_PARM, (obsolete, use PORT_SETTINGS etc. ) */ - GPS_SYNTH, /* | | X | X | SYNTH synthesizer's frequency and phase */ - GPS_ANT_INFO, /* | X | X | | ANT_INFO, time diff after antenna disconnect */ - GPS_UCAP, /* | X | X | | TTM, user capture events */ - GPS_ENABLE_FLAGS, /* | | X | X | ENABLE_FLAGS, when to enable serial, pulses, and synth */ - GPS_STAT_INFO, /* | | X | | STAT_INFO, request SV, mode and DAC info */ - GPS_SWITCH_PARMS, /* | | X | X | (obsolete, use GPS_POUT_PROG_IDX) */ - GPS_STRING_PARMS, /* | | X | X | (obsolete, use GPS_PORT_INFO/GPS_PORT_SETTINGS */ - GPS_ANT_CABLE_LENGTH, /* | | X | X | ANT_CABLE_LEN, length of antenna cable */ - GPS_SYNC_OUTAGE_DELAY, /* | | X | X | (customized firmware only) */ - GPS_PULSE_INFO, /* | | X | X | (customized firmware only) */ - GPS_OPT_FEATURES, /* | | X | | (obsolete, use GPS_RECEIVER_INFO) */ - GPS_IRIG_TX_SETTINGS, /* | | X | X | IRIG_SETTINGS, (only if GPS_HAS_IRIG_TX) */ - GPS_RECEIVER_INFO, /* | | X | | RECEIVER_INFO, model specific info */ - GPS_STR_TYPE_INFO_IDX, /* | | X | | STR_TYPE_INFO_IDX, names and modes of supp. string types */ - GPS_PORT_INFO_IDX, /* | | X | | PORT_INFO_IDX, port settings + additional info */ - GPS_PORT_SETTINGS_IDX, /* | | X | X | PORT_SETTINGS_IDX, settings for specified port */ - GPS_POUT_INFO_IDX, /* | | X | | POUT_INFO_IDX, pout settings + additional info */ - GPS_POUT_SETTINGS_IDX, /* | | X | X | POUT_SETTINGS_IDX, programmable pulse output cfg */ - GPS_IRIG_TX_INFO, /* | | X | | IRIG_INFO, (only if GPS_HAS_IRIG_TX) */ - GPS_MULTI_REF_SETTINGS,/* | | X | X | MULTI_REF_SETTINGS, (only if HAS_MULTI_REF) */ - GPS_MULTI_REF_INFO, /* | | X | | MULTI_REF_INFO, (only if HAS_MULTI_REF) */ - GPS_ROM_CSUM, /* | | X | | ROM_CSUM, (not supported by all devices) */ - GPS_MULTI_REF_STATUS, /* | | X | | MULTI_REF_STATUS, (only if HAS_MULTI_REF) */ - GPS_RCV_TIMEOUT, /* | | X | X | RCV_TIMEOUT, [min] (only if HAS_RCV_TIMEOUT) */ - GPS_IGNORE_LOCK, /* | | X | X | IGNORE_LOCK, if != 0 always claim to be sync */ - GPS_IRIG_RX_SETTINGS, /* | | X | X | IRIG_SETTINGS, (only if GPS_HAS_IRIG_RX) */ - GPS_IRIG_RX_INFO, /* | | X | | IRIG_INFO, (only if GPS_HAS_IRIG_RX) */ - GPS_REF_OFFS, /* | | X | X | MBG_REF_OFFS, (only if GPS_HAS_REF_OFFS) */ - GPS_DEBUG_STATUS, /* | | X | | MBG_DEBUG_STATUS, (only if GPS_HAS_DEBUG_STATUS) */ - GPS_XMR_SETTINGS_IDX, /* | | X | X | XMULTI_REF_SETTINGS_IDX, (only if GPS_HAS_XMULTI_REF) */ - GPS_XMR_INFO_IDX, /* | | X | | XMULTI_REF_INFO_IDX, (only if GPS_HAS_XMULTI_REF) */ - GPS_XMR_STATUS_IDX, /* | | X | | XMULTI_REF_STATUS_IDX, (only if GPS_HAS_XMULTI_REF) */ - GPS_OPT_SETTINGS, /* | | X | X | MBG_OPT_SETTINGS, (only if GPS_HAS_OPT_SETTINGS) */ - GPS_OPT_INFO, /* | | X | | MBG_OPT_INFO, (only if GPS_HAS_OPT_SETTINGS) */ - GPS_CLR_UCAP_BUFF, /* | | | X | command only, no data */ - GPS_TIME_SCALE, /* | | X | X | MBG_TIME_SCALE_{SETTINGS|INFO}, (only if GPS_HAS_TIME_SCALE) */ - GPS_NAV_ENG_SETTINGS, /* | | X | X | NAV_ENGINE_SETTINGS, (only if GPS_HAS_NAV_ENGINE_SETTINGS) */ - GPS_RAW_IRIG_DATA, /* | | X | | MBG_RAW_IRIG_DATA, (only if GPS_HAS_RAW_IRIG_DATA) */ - GPS_GPIO_CFG_LIMITS, /* | | X | | MBG_GPIO_CFG_LIMITS, only if GPS_HAS_GPIO */ - GPS_GPIO_INFO_IDX, /* | | X | | MBG_GPIO_INFO_IDX, cfg. and capabilities, only if GPS_HAS_GPIO */ - GPS_GPIO_SETTINGS_IDX, /* | | X | X | MBG_GPIO_SETTINGS_IDX, cfg. of a specific port, only if PCPS_HAS_GPIO */ - GPS_XMR_INSTANCES, /* | | X | X | XMULTI_REF_INSTANCES (only if GPS_HAS_XMULTI_REF) */ - GPS_CLR_EVT_LOG, /* | | | X | clear log command, no data (only if GPS_HAS_EVT_LOG) */ - GPS_NUM_EVT_LOG_ENTRIES, /* | | X | | MBG_NUM_EVT_LOG_ENTRIES, num. of log entries (only if GPS_HAS_EVT_LOG) */ - GPS_FIRST_EVT_LOG_ENTRY, /* | | X | | read oldest MBG_EVT_LOG_ENTRY (only if GPS_HAS_EVT_LOG) */ - GPS_NEXT_EVT_LOG_ENTRY, /* | | X | | read next MBG_EVT_LOG_ENTRY (only if GPS_HAS_EVT_LOG) */ - GPS_LNO_STATUS, /* | | X | | read LNO status */ - - /* GPS data */ - GPS_CFGH = 0x100, /* | | X | X | CFGH, SVs' configuration and health codes */ - GPS_ALM, /* | | X | X | req: uint16_t SV num, SV_ALM, one SV's almanac */ - GPS_EPH, /* | | X | X | req: uint16_t SV num, SV_EPH, one SV's ephemeris */ - GPS_UTC, /* | | X | X | UTC, GPS UTC correction parameters */ - GPS_IONO, /* | | X | X | IONO, GPS ionospheric correction parameters */ - GPS_ASCII_MSG, /* | | X | | ASCII_MSG, the GPS ASCII message */ - - /* Glonass data */ - GPS_GLNS_ALM = 0x200, /* | | X | X | ** preliminary ** */ //##++ - GPS_GNSS_SAT_INFO, /* | | X | | GNSS_SAT_INFO, request SVs */ - GPS_GNSS_MODE, /* | | X | X | MBG_GNSS_MODE_{SETTINGS|INFO}, GNSS operation mode */ - - /* Misc data */ - GPS_IP4_SETTINGS = 0x800, /* | X | X | IP4_SETTINGS, cfg of optional LAN interface */ - GPS_LAN_IF_INFO, /* | X | | LAN_IF_INFO, LAN interface info */ - - /* misc data (SCU) */ - GPS_SCU_STAT = 0x820, /* | X | X | X | SCU_STAT_{SETTINGS|INFO}, SCU board control */ - - GPS_CRYPTED_PACKET = 0x880, /* | X | X | X | encrypted binary packet */ - GPS_CRYPTED_RAW_PACKET, /* | X | X | X | encrypted binary raw packet */ - - GPS_SECU_INFO = 0x900, /* | | X | | encryption method for LAN interface */ - GPS_SECU_SETTINGS, /* | | X | X | reserved for public key LAN interface */ - GPS_SECU_PUBLIC_KEY, /* | | | | settings and password for LAN interface */ - - /* PZF data */ - PZF_PCPS_TIME = 0xA00, /* | | X | X | PCPS_TIME, date/time/status */ - PZF_TR_DISTANCE, /* | | X | X | TR_DISTANCE, dist. from transmitter [km] */ - PZF_TZCODE, /* | | X | X | TZCODE, time zone code */ - PZF_CORR_INFO /* | | X | | CORR_INFO, correlation info */ -}; - -/* - * Caution: If GPS_ALM, GPS_EPH or a code named ..._IDX is sent to retrieve - * some data from a device then an uint16_t parameter must be also supplied - * in order to specify the index number of the data set to be returned. - * The valid index range depends on the command code. - * - * For GPS_ALM and GPS_EPH the index is the SV number which may be 0 or - * MIN_SVNO to MAX_SVNO. If the number is 0, ALL almanacs (32) are returned. - */ - - -typedef struct -{ - GPS_CMD cmd_code; - const char *cmd_name; -} GPS_CMD_NAME_TABLE_ENTRY; - -#define GPS_CMD_NAME_TABLE_ENTRIES \ -{ \ - { GPS_AUTO_ON, "GPS_AUTO_ON" }, \ - { GPS_AUTO_OFF, "GPS_AUTO_OFF" }, \ - { GPS_SW_REV, "GPS_SW_REV" }, \ - { GPS_BVAR_STAT, "GPS_BVAR_STAT" }, \ - { GPS_TIME, "GPS_TIME" }, \ - { GPS_POS_XYZ, "GPS_POS_XYZ" }, \ - { GPS_POS_LLA, "GPS_POS_LLA" }, \ - { GPS_TZDL, "GPS_TZDL" }, \ - { GPS_PORT_PARM, "GPS_PORT_PARM" }, \ - { GPS_SYNTH, "GPS_SYNTH" }, \ - { GPS_ANT_INFO, "GPS_ANT_INFO" }, \ - { GPS_UCAP, "GPS_UCAP" }, \ - { GPS_ENABLE_FLAGS, "GPS_ENABLE_FLAGS" }, \ - { GPS_STAT_INFO, "GPS_STAT_INFO" }, \ - { GPS_SWITCH_PARMS, "GPS_SWITCH_PARMS" }, \ - { GPS_STRING_PARMS, "GPS_STRING_PARMS" }, \ - { GPS_ANT_CABLE_LENGTH, "GPS_ANT_CABLE_LENGTH" }, \ - { GPS_SYNC_OUTAGE_DELAY, "GPS_SYNC_OUTAGE_DELAY" }, \ - { GPS_PULSE_INFO, "GPS_PULSE_INFO" }, \ - { GPS_OPT_FEATURES, "GPS_OPT_FEATURES" }, \ - { GPS_IRIG_TX_SETTINGS, "GPS_IRIG_TX_SETTINGS" }, \ - { GPS_RECEIVER_INFO, "GPS_RECEIVER_INFO" }, \ - { GPS_STR_TYPE_INFO_IDX, "GPS_STR_TYPE_INFO_IDX" }, \ - { GPS_PORT_INFO_IDX, "GPS_PORT_INFO_IDX" }, \ - { GPS_PORT_SETTINGS_IDX, "GPS_PORT_SETTINGS_IDX" }, \ - { GPS_POUT_INFO_IDX, "GPS_POUT_INFO_IDX" }, \ - { GPS_POUT_SETTINGS_IDX, "GPS_POUT_SETTINGS_IDX" }, \ - { GPS_IRIG_TX_INFO, "GPS_IRIG_TX_INFO" }, \ - { GPS_MULTI_REF_SETTINGS, "GPS_MULTI_REF_SETTINGS" }, \ - { GPS_MULTI_REF_INFO, "GPS_MULTI_REF_INFO" }, \ - { GPS_ROM_CSUM, "GPS_ROM_CSUM" }, \ - { GPS_MULTI_REF_STATUS, "GPS_MULTI_REF_STATUS" }, \ - { GPS_RCV_TIMEOUT, "GPS_RCV_TIMEOUT" }, \ - { GPS_IGNORE_LOCK, "GPS_IGNORE_LOCK" }, \ - { GPS_IRIG_RX_SETTINGS, "GPS_IRIG_RX_SETTINGS" }, \ - { GPS_IRIG_RX_INFO, "GPS_IRIG_RX_INFO" }, \ - { GPS_REF_OFFS, "GPS_REF_OFFS" }, \ - { GPS_DEBUG_STATUS, "GPS_DEBUG_STATUS" }, \ - { GPS_XMR_SETTINGS_IDX, "GPS_XMR_SETTINGS_IDX" }, \ - { GPS_XMR_INFO_IDX, "GPS_XMR_INFO_IDX" }, \ - { GPS_XMR_STATUS_IDX, "GPS_XMR_STATUS_IDX" }, \ - { GPS_OPT_SETTINGS, "GPS_OPT_SETTINGS" }, \ - { GPS_OPT_INFO, "GPS_OPT_INFO" }, \ - { GPS_CLR_UCAP_BUFF, "GPS_CLR_UCAP_BUFF" }, \ - { GPS_TIME_SCALE, "GPS_TIME_SCALE" }, \ - { GPS_NAV_ENG_SETTINGS, "GPS_NAV_ENG_SETTINGS" }, \ - { GPS_RAW_IRIG_DATA, "GPS_RAW_IRIG_DATA" }, \ - { GPS_GPIO_CFG_LIMITS, "GPS_GPIO_CFG_LIMITS" }, \ - { GPS_GPIO_INFO_IDX, "GPS_GPIO_INFO_IDX" }, \ - { GPS_GPIO_SETTINGS_IDX, "GPS_GPIO_SETTINGS_IDX" }, \ - { GPS_XMR_INSTANCES, "GPS_XMR_INSTANCES" }, \ - { GPS_CLR_EVT_LOG, "GPS_CLR_EVT_LOG" }, \ - { GPS_NUM_EVT_LOG_ENTRIES, "GPS_NUM_EVT_LOG_ENTRIES" }, \ - { GPS_FIRST_EVT_LOG_ENTRY, "GPS_FIRST_EVT_LOG_ENTRY" }, \ - { GPS_NEXT_EVT_LOG_ENTRY, "GPS_NEXT_EVT_LOG_ENTRY" }, \ - { GPS_LNO_STATUS, "GPS_LNO_STATUS" }, \ - \ - /* GPS data */ \ - { GPS_CFGH, "GPS_CFGH" }, \ - { GPS_ALM, "GPS_ALM" }, \ - { GPS_EPH, "GPS_EPH" }, \ - { GPS_UTC, "GPS_UTC" }, \ - { GPS_IONO, "GPS_IONO" }, \ - { GPS_ASCII_MSG, "GPS_ASCII_MSG" }, \ - \ - /* Glonass data */ \ - { GPS_GLNS_ALM, "GPS_GLNS_ALM" }, \ - { GPS_GNSS_SAT_INFO, "GPS_GNSS_SAT_INFO" }, \ - { GPS_GNSS_MODE, "GPS_GNSS_MODE" }, \ - \ - /* Misc data */ \ - { GPS_IP4_SETTINGS, "GPS_IP4_SETTINGS" }, \ - { GPS_LAN_IF_INFO, "GPS_LAN_IF_INFO" }, \ - \ - /* misc data (SCU) */ \ - { GPS_SCU_STAT, "GPS_SCU_STAT" }, \ - \ - { GPS_CRYPTED_PACKET, "GPS_CRYPTED_PACKET" }, \ - { GPS_CRYPTED_RAW_PACKET, "GPS_CRYPTED_RAW_PACKET" }, \ - \ - { GPS_SECU_INFO, "GPS_SECU_INFO" }, \ - { GPS_SECU_SETTINGS, "GPS_SECU_SETTINGS" }, \ - { GPS_SECU_PUBLIC_KEY, "GPS_SECU_PUBLIC_KEY" }, \ - \ - /* PZF data */ \ - { PZF_PCPS_TIME, "PZF_PCPS_TIME" }, \ - { PZF_TR_DISTANCE, "PZF_TR_DISTANCE" }, \ - { PZF_TZCODE, "PZF_TZCODE" }, \ - { PZF_CORR_INFO, "PZF_CORR_INFO" }, \ - { 0, NULL } \ -} - - -/* A structure holding the number of a SV and the SV's almanac. */ - -typedef struct -{ - SVNO svno; - ALM alm; -} SV_ALM; - - - -/* A structure holding the number of a SV and the SV's ephemeris. */ - -typedef struct -{ - SVNO svno; - EPH eph; -} SV_EPH; - - - -#if _USE_PCPSDEFS - -/* Attention: this differs from PCPS_TZCODE defined in pcpsdefs.h */ -typedef uint16_t TZCODE; - -#endif - - - -/* The message header */ - -typedef struct -{ - GPS_CMD cmd; - uint16_t len; - CSUM data_csum; - CSUM hdr_csum; -} MSG_HDR; - - - -/* A union combining all kinds of parameters to be read from or written */ -/* to the GPS receiver. The size of the union corresponds to the maximum */ -/* size of the data part of a message. */ - -typedef union -{ - /* common types */ - uint16_t us; - double d; - SVNO svno; - - /* user data */ - SW_REV sw_rev; - BVAR_STAT bvar_stat; - TTM ttm; - XYZ xyz; - LLA lla; - TZDL tzdl; - PORT_PARM port_parm; - SYNTH synth; - ANT_INFO ant_info; - TTM ucap; - ENABLE_FLAGS enable_flags; - STAT_INFO stat_info; - ANT_CABLE_LEN ant_cable_len; - IRIG_SETTINGS irig_tx_settings; - RECEIVER_INFO receiver_info; - STR_TYPE_INFO_IDX str_type_info_idx; - PORT_INFO_IDX port_info_idx; - PORT_SETTINGS_IDX port_settings_idx; - POUT_INFO_IDX pout_info_idx; - POUT_SETTINGS_IDX pout_settings_idx; - IRIG_INFO irig_tx_info; - MULTI_REF_SETTINGS multi_ref_settings; - MULTI_REF_INFO multi_ref_info; - ROM_CSUM rom_csum; - MULTI_REF_STATUS multi_ref_status; - RCV_TIMEOUT rcv_timeout; - IGNORE_LOCK ignore_lock; - IRIG_SETTINGS irig_rx_settings; - IRIG_INFO irig_rx_info; - MBG_REF_OFFS ref_offs; - MBG_DEBUG_STATUS debug_status; - XMULTI_REF_SETTINGS_IDX xmulti_ref_settings_idx; - XMULTI_REF_INFO_IDX xmulti_ref_info_idx; - XMULTI_REF_STATUS_IDX xmulti_ref_status_idx; - MBG_OPT_SETTINGS opt_settings; - MBG_OPT_INFO opt_info; - MBG_TIME_SCALE_INFO time_scale_info; - MBG_TIME_SCALE_SETTINGS time_scale_settings; - NAV_ENGINE_SETTINGS nav_engine_settings; - MBG_RAW_IRIG_DATA raw_irig_data; - GNSS_SAT_INFO gnss_sat_info; //##++++++ - MBG_GNSS_MODE_INFO gnss_mode_info; //##++++++ - MBG_GNSS_MODE_SETTINGS gnss_mode_settings; //##++++++ - MBG_GPIO_CFG_LIMITS gpio_cfg_limits; - MBG_GPIO_INFO_IDX gpio_info_idx; - MBG_GPIO_SETTINGS_IDX gpio_settings_idx; - XMULTI_REF_INSTANCES xmulti_ref_instances; - MBG_NUM_EVT_LOG_ENTRIES num_evt_log_entries; - MBG_EVT_LOG_ENTRY evt_log_entry; - LNO_STATE lno_state; - - /* GPS system data */ - CFGH cfgh; - SV_ALM sv_alm; - SV_EPH sv_eph; - UTC utc; - IONO iono; - ASCII_MSG ascii_msg; - - /* Misc data */ - IP4_SETTINGS ip4_settings; - LAN_IF_INFO lan_if_info; - - /* Misc data (SCU) */ - SCU_STAT_INFO scu_stat_info; - SCU_STAT_SETTINGS scu_stat_settings; - -#if _USE_PCPSDEFS - PCPS_TIME pcps_time; - TR_DISTANCE tr_distance; - TZCODE tzcode; - CORR_INFO corr_info; -#endif - -#if _USE_ENCRYPTION - SECU_SETTINGS secu_settings; -#endif - -#if _USE_GPSPRIV - _mbg_gps_types_priv -#endif - -} MSG_DATA; - - -#ifndef MAX_MSG_DATA_SIZE - #ifndef ADD_MSG_DATA_SIZE - #if _USE_ENCRYPTION - #define ADD_MSG_DATA_SIZE AES_BLOCK_SIZE // round up to full paragraphs - #else - #define ADD_MSG_DATA_SIZE 0 - #endif - #endif - - #define MAX_MSG_DATA_SIZE ( sizeof( MSG_DATA ) + ADD_MSG_DATA_SIZE ) -#endif - - - -/* The structures below define parts of a binary message packet which */ -/* are used with encrypted messages, */ - -typedef struct -{ - MSG_HDR hdr; - - #if _USE_ENCRYPTION - uint8_t aes_initvect[AES_BLOCK_SIZE]; - #else - // In this case this structure is just a dummy to avoid - // a compiler error with the function prototypes. - #endif - -} CRYPT_MSG_PREFIX; - - - -#if _USE_ENCRYPTION - -typedef struct -{ - uint8_t aes_initvect[AES_BLOCK_SIZE]; - - struct - { - MSG_HDR enc_hdr; - - union - { - uint8_t bytes[MAX_MSG_DATA_SIZE]; - MSG_DATA msg_data; - } enc_msg; - - } enc_msg; - -} CRYPT_MSG_DATA; - -#endif - - - -/* A buffer holding a message header plus data part of a message */ -/* For portability reasons the CMSG_BUFF structure defined below */ -/* should be preferred for coding. */ - -typedef struct -{ - MSG_HDR hdr; - - union - { - uint8_t bytes[MAX_MSG_DATA_SIZE]; - MSG_DATA msg_data; - - #if _USE_ENCRYPTION - CRYPT_MSG_DATA crypt_msg_data; - #endif - - } u; - -} MBG_MSG_BUFF; - - - -/* The structure below is used to control the reception of messages */ - -typedef struct -{ - MBG_MSG_BUFF *pmb; /* points to unencrypted message buffer */ - int buf_size; /* size of buffer, including header */ - uint8_t *cur; /* points to current pos inside receive buffer */ - int cnt; /* the number of bytes to receive */ - ulong flags; /* flags if header already completed */ - #if _USE_RCV_TSTAMP - MBG_TMO_TIME tstamp; - #endif - #if _USE_CHK_TSTR - void (*chk_tstr_fnc)( char c, CHK_TSTR_ARG *arg ); /* optional handler for normal, non-protocol data */ - CHK_TSTR_ARG *chk_tstr_arg; - #endif - -} MBG_MSG_RCV_CTL; - - -/* The flag bits below and the corresponding bit masks are used - for MBG_MSG_RCV_CTL::flags: */ - -enum -{ - MBG_MSG_RCV_CTL_BIT_RCVD_HDR, - MBG_MSG_RCV_CTL_BIT_MSG_TOO_LONG, - MBG_MSG_RCV_CTL_BIT_OVERFLOW, - MBG_MSG_RCV_CTL_BIT_DECRYPT_ERR, - MBG_MSG_RCV_CTL_BIT_DECRYPTED, - N_MBG_MSG_RCV_CTL_BIT -}; - -#define MBG_MSG_RCV_CTL_RCVD_HDR ( 1UL << MBG_MSG_RCV_CTL_BIT_RCVD_HDR ) -#define MBG_MSG_RCV_CTL_MSG_TOO_LONG ( 1UL << MBG_MSG_RCV_CTL_BIT_MSG_TOO_LONG ) -#define MBG_MSG_RCV_CTL_OVERFLOW ( 1UL << MBG_MSG_RCV_CTL_BIT_OVERFLOW ) -#define MBG_MSG_RCV_CTL_DECRYPT_ERR ( 1UL << MBG_MSG_RCV_CTL_BIT_DECRYPT_ERR ) -#define MBG_MSG_RCV_CTL_DECRYPTED ( 1UL << MBG_MSG_RCV_CTL_BIT_DECRYPTED ) - - -typedef struct -{ - MBG_MSG_BUFF *pmb; - int buf_size; - int xfer_mode; - - #if _USE_MUTEX - MBG_MUTEX xmt_mutex; - #endif - -} MBG_MSG_XMT_CTL; - - -// codes used with MBG_MSG_CTL::xfer_mode: - -enum -{ - MBG_XFER_MODE_NORMAL, - MBG_XFER_MODE_ENCRYTED, - N_MBG_XFER_MODE -}; - - - -#if _USE_SOCKET_IO - -#if !defined ( MBGEXTIO_RCV_TIMEOUT_SOCKET ) - #define MBGEXTIO_RCV_TIMEOUT_SOCKET 2000 // [ms] -#endif - -#define LAN_XPT_PORT 10001 - -#ifndef INVALID_SOCKET - #define INVALID_SOCKET -1 -#endif - -typedef struct -{ - int sockfd; - struct sockaddr_in addr; - -} SOCKET_IO_STATUS; - -#endif // _USE_SOCKET_IO - - -#if _USE_SERIAL_IO - -#endif // _USE_SERIAL_IO - - - -typedef struct -{ - MBG_MSG_RCV_CTL rcv; - MBG_MSG_XMT_CTL xmt; - - int conn_type; - int io_error; - ulong msg_rcv_timeout; // binary message receive timeout [ms] - ulong char_rcv_timeout; // serial character receive timeout [ms] - - #if _USE_ENCRYPTION - uint8_t aes_initvect[AES_BLOCK_SIZE]; - uint8_t aes_keyvect[AES_BLOCK_SIZE]; - #endif - - #if _USE_SOCKET_IO - SECU_SETTINGS secu_settings; - #endif - - #if _USE_SERIAL_IO || _USE_SOCKET_IO || _USE_USB_IO - union - { - #if _USE_SOCKET_IO - SOCKET_IO_STATUS sockio; - #endif - - #if _USE_SERIAL_IO - SERIAL_IO_STATUS serio; - #endif - - #if _USE_USB_IO - USB_IO_STATUS usbio; - #endif - } st; - #endif - -} MBG_MSG_CTL; - - -// codes used with MBG_MSG_CTL::conn_type: - -enum -{ - MBG_CONN_TYPE_SERIAL, - MBG_CONN_TYPE_SOCKET, - MBG_CONN_TYPE_USB, - N_MBG_CONN_TYPE -}; - - - -/* function prototypes: */ - -#if _USE_GPSSERIO_FNC - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - CSUM msg_csum_update( CSUM csum, uint8_t *p, int n ) ; - CSUM msg_csum( uint8_t *p, int n ) ; - CSUM msg_hdr_csum( MSG_HDR *pmh ) ; - int chk_hdr_csum( MSG_HDR *pmh ) ; - int chk_data_csum( MBG_MSG_BUFF *pmb ) ; - int encrypt_message( MBG_MSG_CTL *pmctl, CRYPT_MSG_PREFIX *pcmp, MBG_MSG_BUFF *pmb ) ; - int decrypt_message( MBG_MSG_CTL *pmctl ) ; - void set_encryption_mode( MBG_MSG_CTL *pmctl, int mode, const char *key ) ; - int xmt_tbuff( MBG_MSG_CTL *pmctl ) ; - int xmt_cmd( MBG_MSG_CTL *pmctl, GPS_CMD cmd ) ; - int xmt_cmd_us( MBG_MSG_CTL *pmctl, GPS_CMD cmd, uint16_t us ) ; - int check_transfer( MBG_MSG_RCV_CTL *prctl, uint8_t c ) ; - -/* ----- function prototypes end ----- */ - -#endif // _USE_GPSSERIO_FNC - -/* End of header body */ - - -#undef _ext - -#ifdef __cplusplus -} -#endif - - -#endif /* _GPSSERIO_H */ - diff --git a/c/mbglib/include/gpsutils.h b/c/mbglib/include/gpsutils.h index c2143ca..0454429 100644 --- a/c/mbglib/include/gpsutils.h +++ b/c/mbglib/include/gpsutils.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: gpsutils.h 1.7 2010/07/15 09:32:09Z martin REL_M $ + * $Id: gpsutils.h 1.8 2017/07/05 13:58:25Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,10 @@ * * ----------------------------------------------------------------------- * $Log: gpsutils.h $ - * Revision 1.7 2010/07/15 09:32:09Z martin + * Revision 1.8 2017/07/05 13:58:25Z martin + * Include stddef.h. + * Updated function prototypes. + * Revision 1.7 2010/07/15 09:32:09 martin * Use DEG character definition from pcpslstr.h. * Revision 1.6 2005/02/18 10:32:33Z martin * Check more predefined macros to determine if compiling for Windows. @@ -34,6 +37,8 @@ #include <mbggeo.h> +#include <stddef.h> + #ifdef _GPSUTILS #define _ext @@ -45,28 +50,174 @@ /* Start of header body */ - -/* function prototypes: */ - #ifdef __cplusplus extern "C" { #endif + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ - void swap_double( double *d ) ; - void swap_eph_doubles( EPH *ephp ) ; - void swap_alm_doubles( ALM *almp ) ; - void swap_utc_doubles( UTC *utcp ) ; - void swap_iono_doubles( IONO *ionop ) ; - void swap_pos_doubles( POS *posp ) ; - void sprint_dms( char *s, DMS *pdms, int prec ) ; - void sprint_alt( char *s, double alt ) ; - void sprint_pos_geo( char *s, POS *ppos, const char *sep, int prec ) ; - void sprint_fixed_freq( char *s, FIXED_FREQ_INFO *p_ff ) ; + /** + * @brief Swap the bytes of a single variable of type "double" + * + * The memory layout of a "double" on Meinberg bus level devices + * and computers usually differs. This function can be used to + * fix this and is usually called from inside API functions, + * if required. + * + * @param[in,out] p Pointer to a "double" to be swapped + * + * @see ::swap_eph_doubles + * @see ::swap_alm_doubles + * @see ::swap_utc_doubles + * @see ::swap_iono_doubles + * @see ::swap_pos_doubles + */ + void swap_double( double *p ) ; + + /** + * @brief Swap the "double" fields in an ::EPH structure + * + * See comments for ::swap_double + * + * @param[in,out] p Pointer to an ::EPH structure to be converted + * + * @see ::swap_double + * @see ::swap_alm_doubles + * @see ::swap_utc_doubles + * @see ::swap_iono_doubles + * @see ::swap_pos_doubles + */ + void swap_eph_doubles( EPH *p ) ; + + /** + * @brief Swap the "double" fields in an ::ALM structure + * + * See comments for ::swap_double + * + * @param[in,out] p Pointer to an ::ALM structure to be converted + * + * @see ::swap_double + * @see ::swap_eph_doubles + * @see ::swap_utc_doubles + * @see ::swap_iono_doubles + * @see ::swap_pos_doubles + */ + void swap_alm_doubles( ALM *p ) ; + + /** + * @brief Swap the "double" fields in a ::UTC structure + * + * See comments for ::swap_double + * + * @param[in,out] p Pointer to a ::UTC structure to be converted + * + * @see ::swap_double + * @see ::swap_eph_doubles + * @see ::swap_alm_doubles + * @see ::swap_iono_doubles + * @see ::swap_pos_doubles + */ + void swap_utc_doubles( UTC *p ) ; + + /** + * @brief Swap the "double" fields in a ::IONO structure + * + * See comments for ::swap_double + * + * @param[in,out] p Pointer to a ::IONO structure to be converted + * + * @see ::swap_double + * @see ::swap_eph_doubles + * @see ::swap_alm_doubles + * @see ::swap_utc_doubles + * @see ::swap_pos_doubles + */ + void swap_iono_doubles( IONO *p ) ; + + /** + * @brief Swap the "double" fields in a ::POS structure + * + * See comments for ::swap_double + * + * @param[in,out] p Pointer to a ::POS structure to be converted + * + * @see ::swap_double + * @see ::swap_eph_doubles + * @see ::swap_alm_doubles + * @see ::swap_utc_doubles + * @see ::swap_iono_doubles + */ + void swap_pos_doubles( POS *p ) ; + + /** + * @brief Print the ::DMS part of a geo position into a string buffer + * + * @param[out] s The string buffer to be filled + * @param[in] max_len Size of the output buffer for 0-terminated string + * @param[in] p Pointer to a ::DMS structure to be printed + * @param[in] prec Precision, i.e. number of fractions of the seconds + * + * @return Length of the string in the buffer + * + * @see snprint_dms + * @see snprint_alt + * @see snprint_pos_geo + * @see snprint_fixed_freq + */ + size_t snprint_dms( char *s, size_t max_len, const DMS *p, int prec ) ; + + /** + * @brief Print the altitude part of a geo position into a string buffer + * + * @param[out] s The string buffer to be filled + * @param[in] max_len Size of the output buffer for 0-terminated string + * @param[in] alt The altitude value to be printed, in [m] + * + * @return Length of the string in the buffer + * + * @see snprint_dms + * @see snprint_pos_geo + * @see snprint_fixed_freq + */ + size_t snprint_alt( char *s, size_t max_len, double alt ) ; + + /** + * @brief Print a geo position in ::POS format into a string buffer + * + * @param[out] s The string buffer to be filled + * @param[in] max_len Size of the output buffer for 0-terminated string + * @param[in] p Pointer to a ::POS structure to be printed + * @param[in] sep Separator character for the ::DMS part + * @param[in] prec Precision, i.e. number of fractions of the seconds of the ::DMS part + * + * @return Length of the string in the buffer + * + * @see snprint_dms + * @see snprint_alt + * @see snprint_fixed_freq + */ + size_t snprint_pos_geo( char *s, size_t max_len, const POS *p, char sep, int prec ) ; + + /** + * @brief Print a formatted ::FIXED_FREQ_INFO into a string buffer + * + * @param[out] s The string buffer to be filled + * @param[in] max_len Size of the output buffer for 0-terminated string + * @param[in] p_ff Pointer to a ::FIXED_FREQ_INFO structure to be printed + * + * @return Length of the string in the buffer + * + * @see snprint_dms + * @see snprint_alt + * @see snprint_pos_geo + */ + size_t snprint_fixed_freq( char *s, size_t max_len, FIXED_FREQ_INFO *p_ff ) ; + /* ----- function prototypes end ----- */ diff --git a/c/mbglib/include/lan_util.h b/c/mbglib/include/lan_util.h deleted file mode 100644 index ede3818..0000000 --- a/c/mbglib/include/lan_util.h +++ /dev/null @@ -1,597 +0,0 @@ - -/************************************************************************** - * - * $Id: lan_util.h 1.5.1.2 2014/05/19 14:46:14Z martin TRASH $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for lan_util.c. - * - * ----------------------------------------------------------------------- - * $Log: lan_util.h $ - * Revision 1.5.1.2 2014/05/19 14:46:14Z martin - * Fixed comment grammar. - * Revision 1.5.1.1 2014/01/31 14:45:24 martin - * Revision 1.5 2013/10/02 07:20:36 martin - * Updated function prototypes. - * Revision 1.4 2013/02/19 15:15:53 martin - * Added some inline functions. - * Redefined return codes as named enum. - * Updated function prototypes. - * Revision 1.3 2012/10/02 18:24:29 martin - * Added some macros to simpliy conversion to string. - * Revision 1.2 2012/03/09 08:51:44 martin - * Updated function prototypes. - * Revision 1.1 2011/03/04 10:01:32 martin - * Initial revision. - * - **************************************************************************/ - -#ifndef _LAN_UTIL_H -#define _LAN_UTIL_H - - -/* Other headers to be included */ - -#include <mbg_tgt.h> -#include <gpsdefs.h> // for some Meinberg data structures - -#include <stdlib.h> - -#if defined( MBG_TGT_POSIX ) - #include <sys/types.h> - #include <sys/socket.h> - #include <net/if.h> -#else - // A dummy declaration to prevent from warnings due to usage - // of this type with function prototypes. - struct ifreq - { - int dummy; - }; -#endif - - -#if defined( IFHWADDRLEN ) // usually defined in net/if.h - #if ( IFHWADDRLEN != 6 ) - #error Warning: IFHWADDRLEN is not 6! - #endif -#endif - - - -#ifdef _LAN_UTIL - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment - #define _USING_BYTE_ALIGNMENT -#endif - -#ifdef __cplusplus -extern "C" { -#endif - - -#if !defined( MAC_SEP_CHAR ) - #define MAC_SEP_CHAR ':' // character used to separate octets of a MAC ID -#endif - -#if !defined( MAC_SEP_CHAR_ALT ) - #define MAC_SEP_CHAR_ALT '-' // alternate character -#endif - - -/** - * @brief Return codes for the LAN utility functions - */ -enum MBG_LU_CODES -{ - MBG_LU_SUCCESS = 0, ///< success - MBG_LU_ERR_NSUPP = -1, ///< function not supported - MBG_LU_ERR_PORT_NAME = -2, ///< port name exceeds max length - MBG_LU_ERR_SOCKET = -3, ///< failed to open socket - MBG_LU_ERR_IOCTL = -4, ///< IOCTL call failed - MBG_LU_ERR_NOT_SET = -5, ///< octets are all 0 - MBG_LU_ERR_BUFF_SZ = -6, ///< buffer size too small - MBG_LU_ERR_FMT = -7, ///< parameter format not correct - MBG_LU_ERR_RANGE = -8 ///< range for some parameter exceeded -}; - - -#define MAX_IP4_BITS ( 8 * sizeof( IP4_ADDR ) ) - -#define IP4_MSB_MASK ( 1UL << ( MAX_IP4_BITS - 1 ) ) - -#define MIN_IP4_CIDR_NETMASK_BITS 0 -#define MAX_IP4_CIDR_NETMASK_BITS MAX_IP4_BITS - - - -/** - * @brief Compute an IP4 net mask according to the number of CIDR netmask bits - * - * E.g. the 24 bits mentioned in "172.16.3.250/24" result in 0xFFFFFF00, - * corresponding to 255.255.255.0 in dotted quad notation. - * - * @param netmask_bits Number of netmask bits from CIDR notation - * - * @return The IP4 net mask - * - * @see get_ip4_net_mask_bits() - */ -static __mbg_inline -IP4_ADDR ip4_net_mask_from_cidr( int netmask_bits ) -{ - return (IP4_ADDR) ~( ( 1UL << ( MAX_IP4_BITS - netmask_bits ) ) - 1 ); - -} // ip4_net_mask_from_cidr - - - -/** - * @brief Determine the broadcast address for an IP4 address plus net mask - * - * E.g. IP 0xAC1003FA, net mask 0xFFFFFF00 yields broadcast addr 0xAC1003FF. - * In dotted quad notation, IP 172.16.3.250 with net mask 255.255.255.0 - * result in broadcast address 172.16.3.255. - * - * @param p_addr The full IP4 address - * @param p_mask The IP4 net mask - * - * @return The determined IP4 broadcast address - */ -static __mbg_inline -IP4_ADDR ip4_broad_addr_from_addr( const IP4_ADDR *p_addr, const IP4_ADDR *p_mask ) -{ - return *p_addr | ~(*p_mask); - -} // ip4_broad_addr_from_addr - - - -/** - * @brief Determine the network part of an IP4 address based on the net mask - * - * E.g. IP 0xAC1003FA, net mask 0xFFFFFF00 yields network part 0xAC100300. - * In dotted quad notation, IP 172.16.3.250 with net mask 255.255.255.0 - * results in network part 172.16.3.0. - * - * @param p_addr The full IP4 address - * @param p_mask The IP4 net mask - * - * @return The network part of the IP4 address - */ -static __mbg_inline -IP4_ADDR ip4_net_part_from_addr( const IP4_ADDR *p_addr, const IP4_ADDR *p_mask ) -{ - return *p_addr & *p_mask; - -} // ip4_net_part_from_addr - - - -/** - * @brief Check if two IP4 addresses have the same network part. - * - * @param p_addr1 The first IP4 address to check - * @param p_addr2 The second IP4 address to check - * @param p_mask The IP4 net mask - * - * @return true, if the network parts are matching - */ -static __mbg_inline -int ip4_net_part_matches( const IP4_ADDR *p_addr1, const IP4_ADDR *p_addr2, - const IP4_ADDR *p_mask ) -{ - return ip4_net_part_from_addr( p_addr1, p_mask ) - == ip4_net_part_from_addr( p_addr2, p_mask ); - -} // ip4_net_part_matches - - - -#define _ip4_addr_to_str( _s, _a ) \ - snprint_ip4_addr( _s, sizeof( _s ), _a, NULL ) - -#define _mac_addr_to_str( _s, _a ) \ - snprint_mac_addr( _s, sizeof( _s ), _a ) - - - -/* function prototypes: */ - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - /** - * @brief Count the number of sequential bits set starting from MSB - * - * E.g. for 0xC0 and 0xC1 the results are both 2 since only - * the 2 MSBs are sequentially set. - * - * @param p_mask The IP4 net mask - * - * @return The number of sequential MSB bits set in val - * - * @see ip4_net_mask_from_cidr - */ - int get_ip4_net_mask_bits( const IP4_ADDR *p_mask ) ; - - /** - * @brief Print an IPv4 address to a dotted quad format string. - * - * @param s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param p_addr The IPv4 address - * @param info An optional string which is prepended to the string, or NULL - * - * @return The overall number of characters printed to the string - * - * @see snprint_ip4_cidr_addr - * @see str_to_ip4_addr - * @see cidr_str_to_ip4_addr_and_net_mask - */ - int snprint_ip4_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const char *info ) ; - - /** - * @brief Print an IPv4 address plus net mask to string in CIDR notation. - * - * The printed CIDR string is something like "172.16.3.250/24" - * - * @param s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param p_addr The IPv4 address - * @param p_mask The IPv4 net mask - * @param info An optional string which is prepended to the string, or NULL - * - * @return The overall number of characters printed to the string - * - * @see snprint_ip4_addr - * @see str_to_ip4_addr - * @see cidr_str_to_ip4_addr_and_net_mask - */ - int snprint_ip4_cidr_addr( char *s, size_t max_len, const IP4_ADDR *p_addr, const IP4_ADDR *p_mask, const char *info ) ; - - /** - * @brief Convert a string to an IP4_ADDR. - * - * @param p_addr Pointer to the IP4_ADDR variable, or NULL, in which case this - * function can be used to check if the string is formally correct. - * @param s The string to be converted - * - * @return >= 0 on success, number of characters evaluated from the input string - * -1 if invalid number found in string - * -2 if separator is not a dot '.' - * - * @see snprint_ip4_addr - * @see snprint_ip4_cidr_addr - * @see cidr_str_to_ip4_addr_and_net_mask - */ - int str_to_ip4_addr( IP4_ADDR *p_addr, const char *s ) ; - - /** - * @brief Convert a string in CIDR notation to an IP4_ADDR and net mask. - * - * @param p_addr Pointer to an IP4_ADDR variable for the IP4 address, - * or NULL, in which case this function can be used - * to check if the string is formally correct. - * @param p_mask Pointer to an IP4_ADDR variable for the net mask, - * or NULL, in which case this function can be used - * to check if the string is formally correct. - * @param cidr_str The string to be converted, in CIDR format, e.g. "172.16.3.250/24" - * - * @return >= 0 on success, number of characters evaluated from the input string - * one of the ::MBG_LU_CODES on error - * - * @see snprint_ip4_addr - * @see snprint_ip4_cidr_addr - * @see str_to_ip4_addr - */ - int cidr_str_to_ip4_addr_and_net_mask( IP4_ADDR *p_addr, IP4_ADDR *p_mask, const char *cidr_str ) ; - - /** - * @brief Print a MAC ID or similar array of octets to a string. - * - * @param s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param octets An array of octets - * @param num_octets The number of octets to be printed from the array - * @param sep The separator printed between the bytes, or 0 - * @param info An optional string which is prepended to the output, or NULL - * - * @return The overall number of characters printed to the string - * - * @see snprint_mac_addr - * @see str_to_octets - * @see check_octets_not_all_zero - */ - int snprint_octets( char *s, size_t max_len, const uint8_t *octets, int num_octets, char sep, const char *info ) ; - - /** - * @brief Print a MAC address to a string. - * - * @param s The string buffer into which to print - * @param max_len Maximum length of the string, i.e. size of the buffer - * @param p_mac_addr The MAC address to be printed - * - * @return The overall number of characters printed to the string - * - * @see snprint_octets - * @see str_to_octets - * @see check_octets_not_all_zero - */ - int snprint_mac_addr( char *s, size_t max_len, const MBG_MAC_ADDR *p_mac_addr ) ; - - /** - * @brief Set a MAC ID or a similar array of octets from a string. - * - * @param octets An array of octets to be set up - * @param num_octets The number of octets which can be stored - * @param s The string to be converted - * - * @return The overall number of octets decoded from the string - * - * @see snprint_octets - * @see snprint_mac_addr - * @see check_octets_not_all_zero - */ - int str_to_octets( uint8_t *octets, int num_octets, const char *s ) ; - - /** - * @brief Check if an array of octets is valid, i.e. != 0 - * - * @param octets Pointer to the array of octets - * @param num_octets Number of octets - * - * @return MBG_LU_SUCCESS octets are valid, i.e. not all 0 - * MBG_LU_ERR_NOT_SET octets are invalid, i.e. all 0 - * - * @see snprint_octets - * @see snprint_mac_addr - * @see str_to_octets - */ - int check_octets_not_all_zero( const uint8_t *octets, int num_octets ) ; - - /** - * @brief Check if an array of octets is valid, i.e. != 0 - * - * @param p_addr Pointer to a MAC address - * - * @return MBG_LU_SUCCESS MAC address is valid, i.e. not all 0 - * MBG_LU_ERR_NOT_SET MAC address is invalid, i.e. all 0 - * - * @see check_octets_not_all_zero - */ - int check_mac_addr_not_all_zero( const MBG_MAC_ADDR *p_addr ) ; - - /** - * @brief Do a SIOCGxxx IOCTL call to read specific information from a LAN interface - * - * @param if_name Name of the interface - * @param ioctl_code One of the predefined system SIOCGxxx IOCTL codes - * @param p_ifreq Pointer to a request buffer - * - * @return one of the ::MBG_LU_CODES - */ - int do_siocg_ioctl( const char *if_name, int ioctl_code, struct ifreq *p_ifreq ) ; - - /** - * @brief Retrieve the index of a specific network interface - * - * @param if_name Name of the interface - * @param p_intf_idx Pointer to a variable to be filled up - * - * @return one of the ::MBG_LU_CODES - * on error the MAC addr is set to all 0 - * - * @see get_port_mac_addr_check - */ - int get_port_intf_idx( const char *if_name, int *p_intf_idx ) ; - - /** - * @brief Retrieve the MAC address of a network interface - * - * @param if_name Name of the interface - * @param p_mac_addr Pointer to the MAC address buffer to be filled up - * - * @return one of the ::MBG_LU_CODES - * on error the MAC addr is set to all 0 - * - * @see get_port_mac_addr_check - */ - int get_port_mac_addr( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) ; - - /** - * @brief Retrieve and check the MAC address of a network interface - * - * @param if_name Name of the interface - * @param p_mac_addr Pointer to the MAC address buffer to be filled up - * - * @return one of the ::MBG_LU_CODES - * on error the MAC addr is set to all 0 - * - * @see get_port_mac_addr - */ - int get_port_mac_addr_check( const char *if_name, MBG_MAC_ADDR *p_mac_addr ) ; - - /** - * @brief Check the link state of a network interface - * - * @param if_name Name of the interface - * - * @return 1 link detected on port - * 0 no link detected on port - * one of the ::MBG_LU_CODES in case of an error - */ - int check_port_link( const char *if_name ) ; - - /** - * @brief Retrieve the IPv4 address of a network interface - * - * @param if_name Name of the interface - * @param p_addr Pointer to address field to be filled up - * - * @return one of the ::MBG_LU_CODES - * - * @see get_port_ip4_settings - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr - */ - int get_port_ip4_addr( const char *if_name, IP4_ADDR *p_addr ) ; - - /** - * @brief Retrieve the IPv4 net mask of a network interface - * - * @param if_name Name of the interface - * @param p_addr Pointer to address field to be filled up - * - * @return one of the ::MBG_LU_CODES - * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr - */ - int get_port_ip4_netmask( const char *if_name, IP4_ADDR *p_addr ) ; - - /** - * @brief Retrieve the IPv4 broadcast address of a network interface - * - * @param if_name Name of the interface - * @param p_addr Pointer to address field to be filled up - * - * @return one of the ::MBG_LU_CODES - * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr - */ - int get_port_ip4_broad_addr( const char *if_name, IP4_ADDR *p_addr ) ; - - /** - * @brief Retrieve the IPv4 gateway (default route) - * - * @param p_addr Pointer to address field to be filled up - * - * @return one of the ::MBG_LU_CODES - */ - int get_ip4_gateway( IP4_ADDR *p_addr ) ; - - /** - * @brief Retrieve the IPv4 address of a network interface as string - * - * @param if_name Name of the interface - * @param p_addr_buf Pointer to the string buffer to be filled up - * @param buf_size size of the string buffer - * - * @return one of the ::MBG_LU_CODES - * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr - */ - int get_port_ip4_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) ; - - /** - * @brief Retrieve the IPv4 net mask of a network interface as string - * - * @param if_name Name of the interface - * @param p_addr_buf Pointer to the string buffer to be filled up - * @param buf_size size of the string buffer - * - * @return one of the ::MBG_LU_CODES - * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr - */ - int get_port_ip4_netmask_str( const char *if_name, char *p_addr_buf, int buf_size ) ; - - /** - * @brief Retrieve the IPv4 broadcast address of a network interface as string - * - * @param if_name Name of the interface - * @param p_addr_buf Pointer to the string buffer to be filled up - * @param buf_size size of the string buffer - * - * @return one of the ::MBG_LU_CODES - * - * @see get_port_ip4_settings - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_specific_port_ip4_addr - */ - int get_port_ip4_broad_addr_str( const char *if_name, char *p_addr_buf, int buf_size ) ; - - /** - * @brief Retrieve the current IPv4 settings of a network interface - * - * @param if_name Name of the interface - * @param p Pointer to a IP4_SETTINGS structure to be filled up - * - * @return 0 on success, < 0 on error - * - * @see get_port_ip4_addr - * @see get_port_ip4_addr_str - * @see get_port_ip4_netmask - * @see get_port_ip4_netmask_str - * @see get_port_ip4_broad_addr - * @see get_port_ip4_broad_addr_str - * @see get_specific_port_ip4_addr - */ - int get_port_ip4_settings( const char *if_name, IP4_SETTINGS *p ) ; - - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - - -#if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment - #undef _USING_BYTE_ALIGNMENT -#endif - -/* End of header body */ - - -#undef _ext -#undef _DO_INIT - -#endif /* _LAN_UTIL_H */ - diff --git a/c/mbglib/include/mbg_arch.h b/c/mbglib/include/mbg_arch.h index fa3227c..f803e1d 100644 --- a/c/mbglib/include/mbg_arch.h +++ b/c/mbglib/include/mbg_arch.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_arch.h 1.5 2014/03/11 16:01:55Z martin REL_M $ + * $Id: mbg_arch.h 1.6 2017/01/27 09:03:16Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -14,7 +14,11 @@ * * ----------------------------------------------------------------------- * $Log: mbg_arch.h $ - * Revision 1.5 2014/03/11 16:01:55Z martin + * Revision 1.6 2017/01/27 09:03:16Z martin + * Added macros _mbg_swab8() and _mbg_swab64(). + * Fixed macro syntax. + * Modified _swab_dummy() to avoid compiler warnings due to unused variables. + * Revision 1.5 2014/03/11 16:01:55 martin * Added a comment. * Revision 1.4 2012/10/02 18:32:00 martin * Include words.h and, conditionally, stdlib.h. @@ -70,7 +74,7 @@ // to access unaligned data. #if !defined( _mbg_put_unaligned ) - #define _mbg_put_unaligned( _v, _p ) ((void)( *(_p) = (_v) )) + #define _mbg_put_unaligned( _v, _p ) do { ((void)( *(_p) = (_v) )); } while ( 0 ) #endif #if !defined( _mbg_get_unaligned ) @@ -123,8 +127,9 @@ -// swap a double type variable bytewise e.g. to convert the endianess - +/** + * @brief Swap a 'double' type variable bytewise e.g. to convert the endianess + */ static __mbg_inline void mbg_swab_double( double *p ) { @@ -147,22 +152,27 @@ void mbg_swab_double( double *p ) #if defined( MBG_ARCH_BIG_ENDIAN ) - #define _mbg_swab16( _p ) *(_p) = __swab16( *(_p) ) - #define _mbg_swab32( _p ) *(_p) = __swab32( *(_p) ) + #define _mbg_swab8( _p ) _nop_macro_fnc() // always a dummy, but for completeness ... + #define _mbg_swab16( _p ) do { *(_p) = __swab16( *(_p) ); } while ( 0 ) + #define _mbg_swab32( _p ) do { *(_p) = __swab32( *(_p) ); } while ( 0 ) + #define _mbg_swab64( _p ) do { *(_p) = __swab64( *(_p) ); } while ( 0 ) #define _mbg_swab_double( _p ) mbg_swab_double( _p ) #define _mbg_swab_doubles( _p, _n ) \ + do \ { \ int i; \ for ( i = 0; i < (_n); i++ ) \ _mbg_swab_double( &_p[i] ); \ - } + } while ( 0 ) #else + #define _mbg_swab8( _p ) _nop_macro_fnc() #define _mbg_swab16( _p ) _nop_macro_fnc() #define _mbg_swab32( _p ) _nop_macro_fnc() + #define _mbg_swab64( _p ) _nop_macro_fnc() #define _mbg_swab_double( _p ) _nop_macro_fnc() @@ -170,4 +180,16 @@ void mbg_swab_double( double *p ) #endif + + + +/** + * @brief A placeholder for yet missing _mbg_swab_..() macros + * + * We don't just use the _nop_macro_fnc() macros here to avoid + * compiler warnings 'unused variable'. + */ +#define _mbg_swab_dummy( _x ) do { (void) _x; } while ( 0 ) + + #endif /* _MBG_ARCH_H */ diff --git a/c/mbglib/include/mbg_cof.h b/c/mbglib/include/mbg_cof.h new file mode 100644 index 0000000..3666b1b --- /dev/null +++ b/c/mbglib/include/mbg_cof.h @@ -0,0 +1,83 @@ + +/************************************************************************** + * + * $Id: mbg_cof.h 1.2 2017/07/05 14:25:12Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Container macros (see Linux Kernel) + * + * ----------------------------------------------------------------------- + * $Log: mbg_cof.h $ + * Revision 1.2 2017/07/05 14:25:12Z martin + * Reformatted code to conform to standard header file format. + * Changes tfor improved cross-platform compatibility. + * Revision 1.1 2015/09/09 10:42:27 martin + * Initial revision by philipp. + * + **************************************************************************/ + +#ifndef _MBG_COF_H +#define _MBG_COF_H + +/* Other headers to be included */ + +#include <mbg_tgt.h> + +#if !defined( MBG_TGT_KERNEL ) + #include <stddef.h> // for offsetof() +#endif + + +#ifdef _MBG_COF + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +#if defined( MBG_TGT_POSIX ) + + // A special construct supported by gcc/clang and and implemented + // e.g. in the Linux kernel, which is said to be very type-safe: + #define mbg_container_of( _ptr, _type, _member ) ({ \ + const typeof( ((_type *)0)->_member ) *__mptr = (_ptr); \ + (_type *)((char *)__mptr - offsetof(_type,_member));}) + +#else + + // A different implementation in ANSI C, which supports type-checking anyway: + #define mbg_container_of( _ptr, _type, _member ) \ + ( (_type *)( (char *)(1 ? (_ptr) : &((_type *)0)->_member) - offsetof( _type, _member ))) + +#endif + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + +/* (no header definitions found) */ + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _MBG_COF_H */ diff --git a/c/mbglib/include/mbg_tgt.h b/c/mbglib/include/mbg_tgt.h index b5302d7..f3afe2b 100644 --- a/c/mbglib/include/mbg_tgt.h +++ b/c/mbglib/include/mbg_tgt.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbg_tgt.h 1.32 2014/06/24 09:21:44Z martin REL_M $ + * $Id: mbg_tgt.h 1.46 2019/08/28 12:52:02Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,7 +11,78 @@ * * ----------------------------------------------------------------------- * $Log: mbg_tgt.h $ - * Revision 1.32 2014/06/24 09:21:44Z martin + * Revision 1.46 2019/08/28 12:52:02Z martin + * Changes for mingw. + * Revision 1.45 2019/02/11 09:53:02Z martin + * Support the mingw build environment. + * Changed inclusion of winsock2.h/windows.h on Windows. + * Removed obsolete RCS log entries. + * Revision 1.44 2018/12/11 15:34:15 martin + * Older Visual Studio versions don't support _strtoi64(). + * Revision 1.43 2018/11/22 11:28:01Z martin + * New preprocessor symbol MBG_TGT_USE_IOCTL. + * Provide 'uintptr_t' for old Linux kernels. + * Removed obsolete Windows driver stuff. + * Revision 1.42 2018/09/20 09:40:21 martin + * Define MBG_TGT_MISSTNG_STRTOLL and + * MBG_TGT_MISSING_LLDDIV_T, if appropriate. + * Revision 1.41 2018/08/23 10:49:56Z martin + * Enhanced handling of Windows DDK builds. + * Revision 1.40 2018/07/02 16:57:49Z martin + * Removed obsolete define MBG_USE_MM_IO_FOR_PCI. + * Revision 1.39 2018/06/25 10:52:00 martin + * Support MBG_TGT_NO_TGT. + * Default settings for KERNEL_HAS_BOOL and KERNEL_HAS_TRUE_FALSE + * for Linux can be overridden by project settings. + * Renamed MBG_PRE64_PREFIX to MBG_PRI_64_PREFIX. + * MBG_PRI_64_PREFIX_L or MBG_PRI_64_PREFIX_LL can be used + * to override the defaults with specific project settings. + * MBG_TGT_HAS_DEV_FN is supported on Windows, but + * MBG_TGT_HAS_DEV_FN_BASE is not supported. + * Enhanced debug support for Windows kernel drivers. + * Include limits.h under Windows. + * Defined MBG_TGT_MISSING_STRUCT_TIMESPEC for Borland C. + * Defined __func__ for BC 5 and for DOS, and provide a + * common default declaration.. + * Updated some comments. + * Revision 1.38 2017/08/08 13:07:31 martin + * Proper fix for PRId64 and others. + * Define _CRT_SECURE_NO_WARNINGS only if not already defined. + * Revision 1.37 2017/07/10 07:08:45 thomas-b + * Define PRId64 if it is not defined in inttypes.h + * Revision 1.36 2017/07/04 12:35:11 martin + * Fixed build for Windows kernel space. + * Don't define ssize_t if HAVE_SSIZE_T is already defined. + * Added definition for _NO_MBG_API. + * Fixed missing 'bool' type for old Linux kernels. + * Fixed missing 'struct timespec' for DOS. + * Evaluate preprocessor symbol KERNEL_HAS_BOOL to avoid + * compiler errors due to duplicate definitions in specific + * Linux kernels patched by the distro maintainers. + * Provide ssize_t for C++Builder 5. + * Improved Visual Studio version checking. + * New define MBG_TGT_HAS_NODE_NAME. + * Revision 1.35 2016/08/05 12:21:34 martin + * Conditionally define a macro _DEPRECATED_BY which can be used to + * tag functions as deprecated, so compilers can emit appropriate warnings. + * New symbol MBG_TGT_HAS_ABS64. + * Moved some compatibility definitions from gpsserio.h here. + * Define ssize_t for Windows, if required. + * Conditionally provided struct timespec for Windows. + * Added compatible 64 bit type print format specifiers. + * Include inttypes.h for all targets providing also stdint.h. + * Added some MSVC version code information. + * Fixes for FreeBSD. + * Fixed some spelling. + * Tmp workaround for 2.6.32-5-sparc64. + * Proper fix required. + * Revision 1.34 2015/03/03 13:32:49 martin + * Provide __func__ for MS Visual Studio. + * Revision 1.33 2015/03/02 11:27:59Z martin + * Windows only: + * Define _CRT_SECURE_NO_WARNINGS to quiet compiler warnings. + * Define WIN32_LEAN_AND_MEAN only if it hasn't been defined before. + * Revision 1.32 2014/06/24 09:21:44 martin * Update for newer C++Builder versions. * Revision 1.31 2014/05/27 10:23:33 martin * Finer control of which types are required for or already @@ -72,9 +143,9 @@ * Recognize DOS target under Watcom compilers. * Flag Watcom C always supports wchar_t. * Revision 1.12 2008/01/17 09:38:50Z daniel - * Added macros to determine whether C language extensions + * Added macros to determine whether C language extensions * (e.g. C94, C99) are supported by the target environment. - * Added macro to check whether wchar_t and friends are + * Added macro to check whether wchar_t and friends are * supported, and some compatibility stuff. * Revision 1.11 2007/10/31 16:58:03 martin * Fixed __mbg_inline for Borland C (DOS). @@ -83,7 +154,7 @@ * Added MBG_PORT_HANDLE type for serial ports. * Added macros for unified inline code syntax. * Revision 1.9 2006/12/08 12:45:54Z martin - * Under Windows include ntddk.h rather than windows.h + * Under Windows include ntddk.h rather than windows.h * if building kernel driver . * Revision 1.8 2006/10/25 12:20:45Z martin * Initial support for FreeBSD, NetBSD, and OpenBSD. @@ -100,7 +171,7 @@ * Revision 1.3 2003/04/09 13:37:20Z martin * Added definition for _MBG_API. * Revision 1.2 2003/02/24 16:08:45Z martin - * Don't setup for Win32 PNP if explicitely configured non-PNP. + * Don't setup for Win32 PNP if explicitly configured non-PNP. * Revision 1.1 2002/02/19 13:46:20Z MARTIN * Initial revision * @@ -112,6 +183,10 @@ /* Other headers to be included */ +#ifdef MBG_TGT_NO_TGT + #include <mbg_no_tgt.h> +#else + #ifdef _MBG_TGT #define _ext #else @@ -121,6 +196,25 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + +// The prefix required in a printf() format string to print an +// int64_t type (i.e. "%li", "%lli", "I64i", etc.) may vary depending +// on the compiler type and version, and the associated run time library. +// For user space applications this is usually defined in the header +// files provided by the build environment, but for kernel code there +// are often no such defines, but there are some commonly used defaults. +// This is a hack that can be used to override these defaults in the +// project settings for kernel code, e.g. in the Makefile. +#if defined( MBG_PRI_64_PREFIX_L ) + #define MBG_PRI_64_PREFIX "l" +#elif defined( MBG_PRI_64_PREFIX_LL ) + #define MBG_PRI_64_PREFIX "ll" +#endif + + #if defined( _CVI_ ) #define MBG_TGT_CVI @@ -140,7 +234,7 @@ #if ( _WIN32_WINNT >= 0x0500 ) // Win2k and above #if !defined( MBG_TGT_WIN32_NON_PNP ) - // only if not explicitely disabled + // only if not explicitly disabled #define MBG_TGT_WIN32_PNP #endif #endif @@ -168,7 +262,7 @@ #elif defined( RC_INVOKED ) - //MS resource compiler + // MS resource compiler #define MBG_TGT_WIN32 #elif defined( __WINDOWS_386__ ) @@ -185,6 +279,7 @@ // Watcom C/C++ for target OS/2 #define MBG_TGT_OS2 + #define MBG_TGT_USE_IOCTL 1 #elif defined( __linux ) @@ -211,23 +306,17 @@ // GCC for target OpenBSD #define MBG_TGT_OPENBSD -#elif defined( __sun ) // Oracle Solaris or other SunOS derived operating system +#elif defined( __sun ) // Oracle Solaris or other SunOS derived operating system // __SUNPRO_C Oracle Solaris Studio C compiler, __SUNPRO_C value is the version number // __SUNPRO_CC Oracle Solaris Studio C++ compiler, __SUNPRO_CC value is the version number // __sparc generate code for SPARC (R) architecture (32-bit or 64-bit) - // __sparcv9 generate code for 64-bit SPARC architecture - // __i386 generate code for 32-bit x86 architecture - // __amd64 generate code for 64-bit x64 architecture + // __sparcv9 generate code for 64-bit SPARC architecture + // __i386 generate code for 32-bit x86 architecture + // __amd64 generate code for 64-bit x64 architecture #define MBG_TGT_SUNOS - #define __mbg_inline __inline__ - - #include <stdint.h> - #include <stdbool.h> - #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 - #elif defined( __QNX__ ) // any compiler for target QNX @@ -254,7 +343,7 @@ #if defined( MBG_TGT_FREEBSD ) \ - || defined( MBG_TGT_NETBSD ) \ + || defined( MBG_TGT_NETBSD ) \ || defined( MBG_TGT_OPENBSD ) #define MBG_TGT_BSD @@ -264,18 +353,63 @@ #endif -#if defined( MBG_TGT_LINUX ) \ - || defined( MBG_TGT_BSD ) \ +#if defined( MBG_TGT_LINUX ) \ + || defined( MBG_TGT_BSD ) \ + || defined( MBG_TGT_QNX_NTO ) \ || defined( MBG_TGT_SUNOS ) + #define MBG_TGT_POSIX #define MBG_TGT_UNIX + #endif +#if defined( MBG_TGT_WIN32 ) + + #if !defined( _CRT_SECURE_NO_WARNINGS ) + #define _CRT_SECURE_NO_WARNINGS 1 + #endif + + #include <limits.h> + + #define MBG_TGT_HAS_DEV_FN 1 + #define MBG_TGT_HAS_DEV_FN_BASE 0 + #define MBG_TGT_USE_IOCTL 1 + +#endif // Some definitions depending on the build environment ... -#if defined( __GNUC__ ) +#define FUNC_UNKNOWN "func_???" + +#if defined( __GNUC__ ) || defined( __clang__ ) + + #if defined( __clang__ ) + #define _CLANG_VERSION ( __clang_major__ * 10000 \ + + __clang_minor__ * 100 \ + + __clang_patchlevel__ ) + #endif // defined( __clang__ ) + + #define _GCC_VERSION ( __GNUC__ * 10000 \ + + __GNUC_MINOR__ * 100 \ + + __GNUC_PATCHLEVEL__ ) + + #if defined( __MINGW32__ ) + #define MBG_TGT_MINGW + #endif + + #if defined( __MINGW64__ ) + #define MBG_TGT_MINGW + #endif + + #if defined( MBG_TGT_MINGW ) && defined( __MINGW_EXTENSION ) + // MSYS2 / MinGW defines __MINGW_EXTENSION + // and provides _abs64() and some other stuff, + // but the standard MinGW environment does not. + #if !defined( MBG_TGT_HAS_ABS64 ) + #define MBG_TGT_HAS_ABS64 1 + #endif + #endif #if defined( __i386__ ) @@ -296,7 +430,6 @@ #elif defined( __sparc__ ) #define MBG_ARCH_SPARC - #define MBG_USE_MM_IO_FOR_PCI 1 #define _NO_USE_PACK_INTF @@ -308,21 +441,65 @@ #if defined( MBG_TGT_LINUX ) - #if defined( __KERNEL__ ) + #if defined( MBG_TGT_KERNEL ) #include <linux/types.h> #include <linux/version.h> - #if ( LINUX_VERSION_CODE <= KERNEL_VERSION( 2, 6, 4 ) ) + #if ( LINUX_VERSION_CODE <= KERNEL_VERSION( 2, 6, 4 ) ) || \ + ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 4 ) ) // must be true for 2.6.32-5-sparc64 #define _ULONG_DEFINED 1 #define _USHORT_DEFINED 1 #define _UINT_DEFINED 1 #endif + // The 'bool' type is supported by the vanilla Linux kernel 2.6.19 and later. + #if ( LINUX_VERSION_CODE < KERNEL_VERSION( 2, 6, 19 ) ) + + // However, looks like at least the RedHat folks have backported this + // to 2.6.18, so KERNEL_HAS_BOOL can be defined to avoid a compiler error + // due to a duplicate definition. + #if !defined( KERNEL_HAS_BOOL ) + typedef _Bool bool; + #define bool bool + #endif + + // Similar for 'true' and 'false'. + #if !defined( KERNEL_HAS_TRUE_FALSE ) + enum + { + false, + true + }; + #define falso false + #define true true + #endif + + #endif + + // The 'uintptr_t' type has been introduced + // after v2.6.24-rc1 and before v2.6.24-rc2. + #if ( LINUX_VERSION_CODE < KERNEL_VERSION( 2, 6, 24 ) ) + typedef unsigned long uintptr_t; + #define uintptr_t uintptr_t + #endif + + // String formatter codes like "PRIi64" for int64_t types + // don't seem to be defined in Linux kernel mode, so we + // define the required "ll" or "l" modifier here as a hack. + // Code below uses this to define appropriate "PRIi64"-like + // definitions as "lli" or "li". + #if !defined( MBG_PRI_64_PREFIX ) + // Please note that e.g. Linux 2.6.16 on Itanium (ia64) + // with gcc 4.1.2 expects "%li" to print an int64_t. + // This may be a bug in the specific gcc version, though. + #define MBG_PRI_64_PREFIX "ll" + #endif + #else - #include <sys/types.h> #include <stdint.h> + #include <inttypes.h> #include <stdbool.h> #if defined( __u_char_defined ) @@ -333,18 +510,46 @@ #endif + #define MBG_TGT_HAS_DEV_FN 1 + #define MBG_TGT_HAS_DEV_FN_BASE 1 + #define MBG_TGT_USE_IOCTL 1 + #elif defined( MBG_TGT_BSD ) - #include <sys/types.h> + #if defined( MBG_TGT_KERNEL ) + #include <sys/types.h> + #else + #include <stdint.h> + #include <inttypes.h> + #include <stdbool.h> + #endif + + #define MBG_TGT_HAS_DEV_FN 1 + #define MBG_TGT_HAS_DEV_FN_BASE 1 + #define MBG_TGT_USE_IOCTL 1 + + #if defined( MBG_TGT_FREEBSD ) && defined( MBG_TGT_KERNEL ) + #if !defined( MBG_PRI_64_PREFIX ) + // String formatter codes like "PRIi64" for int64_t types + // don't seem to be defined in FreeBSD kernel mode, so we + // define the required "ll" or "l" modifier here as a hack. + // Code below uses this to define appropriate "PRIi64"-like + // definitions as "lli" or "li". + #define MBG_PRI_64_PREFIX "l" + #endif + #endif #elif defined( MBG_TGT_QNX_NTO ) // QNX 6.x (Neutrino) + #include <unistd.h> #include <stdint.h> + #include <inttypes.h> #include <stdbool.h> #else #include <stdint.h> + #include <inttypes.h> #include <stdbool.h> #endif @@ -353,34 +558,169 @@ #define MBG_TGT_HAS_WCHAR_T 1 - #define __mbg_inline __inline__ + + #if defined( __clang__ ) + #define _DEPRECATED_BY( _s ) __attribute__((deprecated("use \"" _s "\" instead"))) // works with clang 3.4.1 + #elif ( _GCC_VERSION > 40500 ) // gcc 4.5.0 and newer + #define _DEPRECATED_BY( _s ) __attribute__((deprecated("use \"" _s "\" instead"))) + #elif ( _GCC_VERSION > 30100 ) // gcc 3.1 and newer + #define _DEPRECATED_BY( _s ) __attribute__((deprecated)) + #else + // Not supported at all, use empty default definiton below. + #endif + + #if ( _GCC_VERSION > 30100 ) // gcc 3.1 and newer + #define __mbg_inline __inline__ __attribute__((always_inline)) + #else + // Not supported at all, use empty default definiton below. + #define __mbg_inline __inline__ + #endif #elif defined( _MSC_VER ) // Known predifined MS compiler version codes: + // 1910: MSVC++ 15.0 (Visual Studio 2017) + // 1900: MSVC++ 14.0 (Visual Studio 2015) + // 1800: MSVC++ 12.0 (Visual Studio 2013) // 1700: MSVC++ 11.0 (Visual Studio 2012) // 1600: MSVC++ 10.0 (Visual Studio 2010) // 1500: MSVC++ 9.0 (Visual Studio 2008) - // 1400: MSVC++ 8.0 (Visual Studio 2005) - // 1310: MSVC++ 7.1 (Visual Studio 2003) - // 1300: MSVC++ 7.0 + // 1400: MSVC++ 8.0 (Visual Studio 2005, Windows Server 2003 SP1 DDK - AMD64) + // 1310: MSVC++ 7.1 (Visual Studio .NET 2003, Windows Server 2003 DDK) + // 1300: MSVC++ 7.0 (Visual Studio .NET 2002, Windows XP SP1 DDK / DDK 2600) // 1200: MSVC++ 6.0 // 1100: MSVC++ 5.0 - #if ( _MSC_VER >= 1600 ) + // Enable this to get compile-time messages on the compiler version + #if 0 + #if ( _MSC_VER >= 1910 ) + #error >= 1910: MSVC++ 15.0 (Visual Studio 2017), or later + #elif ( _MSC_VER >= 1900 ) + #error 1900: MSVC++ 14.0 (Visual Studio 2015) + #elif ( _MSC_VER >= 1800 ) + #error 1800: MSVC++ 12.0 (Visual Studio 2013) + #elif ( _MSC_VER >= 1700 ) + #error 1700: MSVC++ 11.0 (Visual Studio 2012) + #elif ( _MSC_VER >= 1600 ) + #error 1600: MSVC++ 10.0 (Visual Studio 2010) + #elif ( _MSC_VER >= 1500 ) + #error 1500: MSVC++ 9.0 (Visual Studio 2008) + #elif ( _MSC_VER >= 1400 ) + #error STRINGIFY( _MSC_VER ) MSVC++ 8.0 (Visual Studio 2005, Windows Server 2003 SP1 DDK - AMD64) + #elif ( _MSC_VER >= 1310 ) + #error 1310: MSVC++ 7.1 (Visual Studio .NET 2003, Windows Server 2003 DDK) + #elif ( _MSC_VER >= 1300 ) + #error 1300: MSVC++ 7.0 (Visual Studio .NET 2002, Windows XP SP1 DDK / DDK 2600) + #elif ( _MSC_VER >= 1200 ) + #error 1200: MSVC++ 6.0 + #elif ( _MSC_VER >= 1100 ) + #error 1100: MSVC++ 5.0 + #else + #error <1100: Older than MSVC 4 + #endif + #endif + + // "struct timespec" is supported only since VS2015 + // If it is then also the symbol TIME_UTC should be defined. + // Functions to read the current time as struct timespec + // are timespec_get() and friends, which are also only provided + // by VS2015 and later. + // As of VS2015, only TIME_UTC is supported to read + // the UTC system time, there is no equivalent for + // the POSIX CLOCK_MONOTONIC. However, QPC can be used + // to get monotonic time stamps and intervals. + #if ( _MSC_VER < 1900 ) + #if !defined( HAVE_STRUCT_TIMESPEC ) + #define MBG_TGT_MISSING_STRUCT_TIMESPEC 1 + #endif + #endif + + #if ( _MSC_VER >= 1600 ) // TODO Eventually even 1600 doesn't support this. #include <stdint.h> - #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #include <inttypes.h> + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + + #if !defined( PRId64 ) + #define MBG_PRI_64_PREFIX "I64" + #endif #else - #define MBG_TGT_HAS_INT_8_16_32 1 + #define MBG_TGT_HAS_INT_8_16_32 1 + #define MBG_PRI_64_PREFIX "I64" #endif - // no bool support anyway - #define MBG_TGT_MISSING_BOOL_TYPE 1 + #if !defined( __cplusplus ) + // no bool support anyway + #define MBG_TGT_MISSING_BOOL_TYPE 1 + #endif - #define MBG_TGT_HAS_WCHAR_T 1 + #define MBG_TGT_HAS_WCHAR_T 1 #define __mbg_inline __forceinline + // At least up to VS2008 the C99 builtin symbol __func__ + // is not supported. Some VS versions support __FUNCTION__ + // instead, but at least VC6 doesn't support this, either. + // of the current function instead. + #if ( _MSC_VER >= 1300 ) + #define __func__ __FUNCTION__ + #else + #define __func__ FUNC_UNKNOWN + #endif + + // The "deprecated" attribute should be supported since Visual Studio 2005, + // but doesn't seem to be supported e.g. by the compiler shipped with the + // "Windows Server 2003 SP1 DDK", which is used to build kernel drivers + // and defines the same _MSC_VER number as VS2005. For now we assume + // that this is supported by compilers shipped with newer DDKs. + // The _DDK_BUILD_ symbol has to be explicitly defined in the "sources" + // file of the DDK project. + #if ( ( _MSC_VER >= 1500 ) || \ + ( ( _MSC_VER >= 1400 ) && !defined( _DDK_BUILD_ ) ) ) + #define _DEPRECATED_BY( _s ) __declspec(deprecated("deprecated, use \"" _s "\"")) + #endif + + // availability of _abs64() + #if ( _MSC_VER >= 1310 ) + // This is supported at least since Visual Studio 2008 + // and Windows Server 2003 SP1 DDK. + + #if !defined( MBG_TGT_HAS_ABS64 ) + #define MBG_TGT_HAS_ABS64 1 + #endif + #endif + + #if !defined ( HAVE_SSIZE_T ) + + // ssize_t support + #if ( _MSC_VER >= 1500 ) + // ssize_t may not be defined, but SSIZE_T is + #include <basetsd.h> + typedef SSIZE_T ssize_t; + #else + // At least VC6 hasn't SIZE_T, either, but size_t + // is typedef'ed as unsigned int, so we just typedef + // the signed variant here. + typedef int ssize_t; + #endif + + #define HAVE_SSIZE_T 1 + + #endif // !defined ( HAVE_SSIZE_T ) + + #if ( _MSC_VER <= 1500 ) + // At least MSVC++ 9.0 / Visual Studio 2008 and older + // don't provide lldiv_t and lldiv(). + #define MBG_TGT_MISSING_LLDIV_T 1 + #endif + + #if ( _MSC_VER <= 1400 ) + #define MBG_TGT_MISSING_STRTOLL 1 + #elif ( _MSC_VER <= 1600 ) + // At least MSVC++ 10.0 / Visual Studio 2010 and older + // don't provide strtoll(), but may provide _strtoi64 instead. + #define strtoll _strtoi64 + #endif + #elif defined( _CVI_ ) // 1000 for CVI v10.0 (CVI 2010) @@ -393,6 +733,7 @@ #if ( _CVI_ >= 910 ) // LabWindows/CVI 2009 is the first version providing stdint.h. #include <stdint.h> + #include <inttypes.h> #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 #else #define USE_LONG_FOR_INT32 1 @@ -432,26 +773,46 @@ #if ( __BORLANDC__ >= 0x630 ) // C++Builder XE starts to provide stdbool.h #include <stdint.h> + #include <inttypes.h> #include <stdbool.h> - #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 #elif ( __BORLANDC__ >= 0x570 ) - // at least BDS 2006 starts to provide stdint.h + // BDS/Borland C++ Builder 2006 starts to provide at least stdint.h #include <stdint.h> - #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 - #define MBG_TGT_MISSING_BOOL_TYPE 1 + #include <inttypes.h> + #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 + #if !defined( __cplusplus ) + #define MBG_TGT_MISSING_BOOL_TYPE 1 + #endif #elif ( __BORLANDC__ >= 0x0550 ) - #define MBG_TGT_HAS_INT_8_16_32 1 - #define MBG_TGT_MISSING_BOOL_TYPE 1 + #define MBG_TGT_HAS_INT_8_16_32 1 + #define MBG_PRI_64_PREFIX "I64" + #if !defined( __cplusplus ) + #define MBG_TGT_MISSING_BOOL_TYPE 1 + #endif + #define __func__ FUNC_UNKNOWN #else // e.g. BC 3.1 or earlier #if ( __BORLANDC__ <= 0x410 ) - #define MBG_TGT_MISSING_64_BIT_TYPES 1 - #define MBG_TGT_MISSING_BOOL_TYPE 1 - #define USE_LONG_FOR_INT32 1 + #define MBG_TGT_MISSING_64_BIT_TYPES 1 + #define MBG_TGT_MISSING_BOOL_TYPE 1 + #define USE_LONG_FOR_INT32 1 + #define MBG_TGT_MISSING_STRUCT_TIMESPEC 1 + #define __func__ __FILE__ ":" STRINGIFY(__LINE__) + + typedef int ssize_t; #endif #endif + #if ( __BORLANDC__ <= 0x0550 ) + // At least CBuilder 5 and earlier. + #define MBG_TGT_MISSING_STRTOLL 1 + #define MBG_TGT_MISSING_LLDIV_T 1 + #endif + #define MBG_TGT_HAS_WCHAR_T defined( MBG_TGT_WIN32 ) + #define MBG_TGT_MISSING_STRUCT_TIMESPEC 1 + #if defined( __cplusplus ) #define __mbg_inline inline // standard C++ syntax #elif ( __BORLANDC__ > 0x410 ) // BC3.1 defines 0x410 ! @@ -460,6 +821,11 @@ #define __mbg_inline // up to BC3.1 not supported for C #endif + #if !defined ( HAVE_SSIZE_T ) + typedef int ssize_t; // required at least for C++ Builder 5 + #define HAVE_SSIZE_T 1 + #endif + #elif defined( __WATCOMC__ ) // 1050 v10.5 @@ -472,15 +838,16 @@ #include <sys/types.h> - #define MBG_TGT_MISSING_64_BIT_TYPES 1 + #define MBG_TGT_MISSING_64_BIT_TYPES 1 #elif ( __WATCOMC__ > 1230 ) // Open Watcom C 1.3 and above #include <stdint.h> + #include <inttypes.h> #elif !defined( __WATCOM_INT64__ ) // Watcom C 11 - #define MBG_TGT_MISSING_64_BIT_TYPES 1 + #define MBG_TGT_MISSING_64_BIT_TYPES 1 #endif @@ -491,15 +858,39 @@ #endif +#if !defined( MBG_TGT_USE_IOCTL ) + #define MBG_TGT_USE_IOCTL 0 +#endif + + +// If the build environment doesn't provide an inttypes.h file +// with print format specifiers for 64 bit fixed size types +// then MBG_PRI_64_PREFIX should be defined, which is used +// to define our own C99 compatible format specifiers. +// Eventually, similar definitions are required for 32, 16, +// and 8 bit fixed size types. +#if defined( MBG_PRI_64_PREFIX ) + #define PRIi64 MBG_PRI_64_PREFIX "i" + #define PRId64 MBG_PRI_64_PREFIX "d" + #define PRIo64 MBG_PRI_64_PREFIX "o" + #define PRIu64 MBG_PRI_64_PREFIX "u" + #define PRIx64 MBG_PRI_64_PREFIX "x" + #define PRIX64 MBG_PRI_64_PREFIX "X" +#endif + #if !defined( __GNUC__ ) && !defined( __attribute__ ) #define __attribute__( _x ) #endif +#if !defined( _DEPRECATED_BY ) + #define _DEPRECATED_BY( _s ) // empty definition +#endif + #if defined( MBG_TGT_WIN32 ) #if defined( _AMD64_ ) - // This is used for AMD64 architecture and for + // This is used for AMD64 architecture and for // Intel XEON CPUs with 64 bit extension. #define MBG_TGT_WIN32_PNP_X64 #define WIN32_FLAVOR "x64" @@ -510,13 +901,25 @@ #if defined( _KDD_ ) #define MBG_TGT_KERNEL + #include <ntddk.h> + + #if defined( DBG ) && DBG + #define DEBUG 1 + #endif + + #define _MBG_API #else // This must not be used for kernel drivers. - #define WIN32_LEAN_AND_MEAN 1 - #define _WINSOCKAPI_ /* Prevent inclusion of winsock.h in windows.h */ + + // Prevent inclusion of obsolete winsock.h in windows.h + #if !defined( WIN32_LEAN_AND_MEAN ) + #define WIN32_LEAN_AND_MEAN 1 + #endif + #include <winsock2.h> #include <windows.h> + #include <ws2tcpip.h> typedef HANDLE MBG_HANDLE; @@ -538,14 +941,22 @@ typedef DWORD DWORD_PTR; #endif - #endif + // socklen_t support + #if ( _MSC_VER < 1500 ) + // At least VS2008 has a socklen_t type + typedef int socklen_t; + #endif - #define _MBG_API WINAPI + #define _MBG_API WINAPI - #if defined( MBG_LIB_EXPORT ) - #define _MBG_API_ATTR __declspec( dllexport ) - #else - #define _MBG_API_ATTR __declspec( dllimport ) + #endif + + #if !defined( MBG_TGT_MINGW ) // not required for MinGW + #if defined( MBG_LIB_EXPORT ) + #define _MBG_API_ATTR __declspec( dllexport ) + #elif !defined( MBGSVCTL_STATIC_LIB ) + #define _MBG_API_ATTR __declspec( dllimport ) + #endif #endif #elif defined( MBG_TGT_POSIX ) @@ -569,6 +980,44 @@ #endif +/** + * @brief A socket file descriptor type + */ +#if defined( MBG_TGT_WIN32 ) // && !defined( MBG_TGT_MINGW ) + #if !defined( MBG_TGT_KERNEL ) // we don't need this in kernel space + // usually evaluates to UINT_PTR, which in turn evaluates + // to (unsigned int), or (unsigned __int64). + typedef SOCKET MBG_SOCK_FD; + #endif +#elif defined( MBG_TGT_POSIX ) + typedef int MBG_SOCK_FD; //### TODO + //### TODO typedef int SOCKET; +#endif + + + +/** + * @brief A value to mark an ::MBG_SOCK_FD as invalid + */ +#if defined( MBG_TGT_WIN32 ) + #define MBG_INVALID_SOCK_FD INVALID_SOCKET // usually evaluates to (SOCKET)(~0) since SOCKET is unsigned +#elif defined( MBG_TGT_POSIX ) + #define MBG_INVALID_SOCK_FD -1 +#endif + + + +/** + * @brief The return code of socket functions in case of error + */ +#if defined( MBG_TGT_WIN32 ) + #define MBG_SOCKET_ERR_RETVAL SOCKET_ERROR // usually evaluates to -1 +#elif defined( MBG_TGT_POSIX ) + #define MBG_SOCKET_ERR_RETVAL -1 +#endif + + + #if !defined( _MBG_API ) #define _MBG_API #endif @@ -577,6 +1026,10 @@ #define _MBG_API_ATTR #endif +#if !defined( _NO_MBG_API ) + #define _NO_MBG_API +#endif + #if !defined( _NO_MBG_API_ATTR ) #define _NO_MBG_API_ATTR #endif @@ -585,10 +1038,26 @@ #define MBG_INVALID_PORT_HANDLE MBG_INVALID_HANDLE #endif -#if !defined( MBG_USE_MM_IO_FOR_PCI ) - #define MBG_USE_MM_IO_FOR_PCI 0 +#if !defined( MBG_TGT_HAS_DEV_FN ) + #define MBG_TGT_HAS_DEV_FN 0 #endif +#if !defined( MBG_TGT_HAS_DEV_FN_BASE ) + #define MBG_TGT_HAS_DEV_FN_BASE 0 +#endif + +#if defined( MBG_TGT_MISSING_STRUCT_TIMESPEC ) + + #include <time.h> + + struct timespec + { + time_t tv_sec; + long tv_nsec; + }; + +#endif // defined( MBG_TGT_MISSING_STRUCT_TIMESPEC ) + // The macros below are defined in order to be able to check if // certain C language extensions are available on the target system: @@ -623,17 +1092,6 @@ -/* End of header body */ - -#undef _ext - - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -647,5 +1105,10 @@ extern "C" { } #endif +/* End of header body */ + +#undef _ext + +#endif // !defined( MBG_TGT_NO_TGT ) -#endif /* _MBG_TGT_H */ +#endif // !defined( _MBG_TGT_H ) diff --git a/c/mbglib/include/mbg_w32.h b/c/mbglib/include/mbg_w32.h deleted file mode 100644 index ebdc119..0000000 --- a/c/mbglib/include/mbg_w32.h +++ /dev/null @@ -1,309 +0,0 @@ - -/************************************************************************** - * - * $Id: mbg_w32.h 1.7 2012/05/30 13:28:43Z martin TEST $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * OS dependend definitions/redefinitions for Win32. - * - * ----------------------------------------------------------------------- - * $Log: mbg_w32.h $ - * Revision 1.7 2012/05/30 13:28:43Z martin - * Cleanup. - * Revision 1.6 2012/05/29 14:39:53Z martin - * Runtime support for precise time API introduced with Windows 8. - * Revision 1.5 2009/03/26 08:32:26Z martin - * Added orgDeviceExtension field for non-PNP driver. - * Revision 1.4 2009/01/13 14:45:17Z martin - * Added PCPS_DDEV::RegistryPath field for non-PnP driver. - * Use PCPS_DDEV::irp and PCPS_DDEV::win32DeviceName also for non-PnP driver. - * Added PCPS_DDEV::DriverObject field. - * Conditionally added PCPS_DDEV fields required to support programmable IRQs. - * Revision 1.3 2007/09/27 10:36:25Z martin - * Added macro specifying Windows specific device data. - * Added USB support. - * Renamed Removed to SurpriseRemoved. - * Revision 1.2 2002/01/24 09:48:05Z Udo - * check in as lib module - * Revision 1.1 2001/09/13 07:12:14Z Udo - * Initial revision - * - **************************************************************************/ - -#ifndef _MBG_W32_H -#define _MBG_W32_H - - -/* Other headers to be included */ - -#include <mbg_tgt.h> -#include <words.h> - -#if defined( MBG_TGT_WIN32_PNP ) && defined( MBG_TGT_KERNEL ) - #include <usb100.h> - #include <usbdi.h> - #include <usbdlib.h> -#endif - - -#ifdef _MBG_W32 - #define _ext -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if USE_PGMB_IRQ - - typedef struct - { - struct _KINTERRUPT *Object; - KEVENT *Event; - KSPIN_LOCK Spinlock; - KDPC *Dpc; - } MBG_IRQ_INFO; - - #define _pgmb_irq_vars \ - MBG_IRQ_INFO Irq; - -#else - - #define _pgmb_irq_vars - -#endif - - - -/** - * @brief A pointer to a function returning the system time as LARGE_INTEGER. - * - * This is for kernel mode only. The function can be e.g. the standard Windows - * API call KeQuerySystemTime() or the KeQuerySystemTimePrecise() API - * call introduced with Windows 8. - */ -typedef VOID (*KE_QUERY_SYSTEM_TIME_FNC)(PLARGE_INTEGER CurrentTime); - - - -#if defined( MBG_TGT_KERNEL ) - -#if !defined( NTKERNELAPI ) - #define NTKERNELAPI -#endif - -#if !defined( __in ) - #define __in -#endif - -#if !defined( _Out_ ) - #define _Out_ -#endif - - -#if 0 //##++ - #define _x_evt_msg _evt_msg -#else - #define _x_evt_msg _dbg_evt_msg -#endif - - - -// definitions for clock() support in kernel drivers - -#define clock_t ulong - -#define clock w32_clock - -// KeQueryTimeIncrement() returns number of 100nsec increments per tick. -// There are 10000000 100nsec increments per second. -#define MBG_TICKS_PER_SEC ( 10000000 / KeQueryTimeIncrement() ) - - -/** - * @brief Get precise Windows system time as FILETIME. - * - * @note This function has been introduced with Windows 8, - * so it is not available on older Windows versions. Thus - * the API call is imported from ntoskrnl.exe at runtime. - * - * @param CurrentTime pointer to a LARGE_INTEGER to be filled - * - * @see KE_QUERY_SYSTEM_TIME_FNC - * @see import_kernel_precise_time_api() - */ -NTKERNELAPI -VOID -KeQuerySystemTimePrecise( _Out_ PLARGE_INTEGER CurrentTime); - - - -#if defined( MBG_TGT_WIN32_PNP ) - - #if !defined ( SE_CREATE_SYMBOLIC_LINK_PRIVILEGE ) - - // Define some KDD function types which may not be - // defined in older DDK headers. - - typedef - NTSTATUS - IO_COMPLETION_ROUTINE ( - PDEVICE_OBJECT DeviceObject, - PIRP Irp, - PVOID Context - ); - - typedef IO_COMPLETION_ROUTINE *PIO_COMPLETION_ROUTINE; - - - typedef - NTSTATUS - DRIVER_DISPATCH ( - __in struct _DEVICE_OBJECT *DeviceObject, - __in struct _IRP *Irp - ); - - typedef DRIVER_DISPATCH *PDRIVER_DISPATCH; - - - typedef - VOID - DRIVER_UNLOAD ( - __in struct _DRIVER_OBJECT *DriverObject - ); - - typedef DRIVER_UNLOAD *PDRIVER_UNLOAD; - - - typedef - NTSTATUS - DRIVER_ADD_DEVICE ( - __in struct _DRIVER_OBJECT *DriverObject, - __in struct _DEVICE_OBJECT *PhysicalDeviceObject - ); - - typedef DRIVER_ADD_DEVICE *PDRIVER_ADD_DEVICE; - - #endif // !defined ( SE_CREATE_SYMBOLIC_LINK_PRIVILEGE ) - - - - #define MBG_USB_MAX_NUMBER_OF_ENDPOINTS 32 - #define MBG_USB_MAX_NUMBER_OF_INTERFACES 1 - #define MBG_USB_DEFAULT_TIMEOUT 5000 - #define MBG_USB_MAX_CONTROL_TRANSFER_TIMEOUT 5000 - - - #pragma pack( 4 ) //##++++++ this should be obsolete - - typedef struct - { - long usage_count; - int remove_pending; - KEVENT event; - } USB_REMOVE_LOCK; - - - typedef struct - { - int address; - USBD_PIPE_HANDLE handle; - } USB_ENDPOINT; - - - typedef struct - { - int valid; - int claimed; - USB_ENDPOINT endpoints[MBG_USB_MAX_NUMBER_OF_ENDPOINTS]; - } USB_INTERFACE; - - #pragma pack() - - - - #define _pcps_ddev_data_win_pnp \ - DEVICE_OBJECT *physical_device_object; \ - USB_REMOVE_LOCK remove_lock; \ - \ - struct \ - { \ - USBD_CONFIGURATION_HANDLE handle; \ - int value; \ - USB_INTERFACE interfaces[MBG_USB_MAX_NUMBER_OF_INTERFACES]; \ - } config; \ - \ - LONG ref_count; \ - POWER_STATE power_state; \ - DEVICE_POWER_STATE device_power_states[PowerSystemMaximum]; \ - \ - DEVICE_OBJECT *NextLowerDriver; \ - BOOLEAN Started; \ - BOOLEAN SurpriseRemoved; \ - IO_REMOVE_LOCK RemoveLock; \ - BOOLEAN PortWasMapped; - -#else // if !defined( MBG_TGT_WIN32_PNP ) - - // Don't need PNP extensions in non-PNP environment. - #define _pcps_ddev_data_win_pnp \ - UNICODE_STRING *RegistryPath; \ - PVOID orgDeviceExtension; - -#endif // !defined( MBG_TGT_WIN32_PNP ) - - - #define _pcps_ddev_data_win \ - DRIVER_OBJECT *DriverObject; \ - DEVICE_OBJECT *DeviceObject; \ - UNICODE_STRING win32DeviceName; \ - WCHAR wcs_msg[512]; \ - IRP *irp; \ - _pgmb_irq_vars \ - _pcps_ddev_data_win_pnp - -#endif // defined( MBG_TGT_KERNEL ) - - - -#ifdef __cplusplus -extern "C" { -#endif - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - clock_t w32_clock( void ) ; - /** - * @brief Try to import an API function to read precise Windows system time - * - * Check if the Windows API call KeQuerySystemTimePrecise() is available - * in kernel mode. This function has been introduced with Windows 8, so it - * is not available on older Windows versions, and thus the API call is - * imported from ntoskrnl.exe at runtime. - * - * @param fnc address of a function pointer which is set to the imported - * API function, or to NULL if the API call is not supported - * - * @see KeQuerySystemTimePrecise() - */ - void import_kernel_precise_time_api( KE_QUERY_SYSTEM_TIME_FNC *fnc ) ; - - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - -/* End of header body */ - -#undef _ext - -#endif /* _MBG_W32_H */ - diff --git a/c/mbglib/include/mbgdevio.h b/c/mbglib/include/mbgdevio.h index 8c56a98..c9c80a7 100644 --- a/c/mbglib/include/mbgdevio.h +++ b/c/mbglib/include/mbgdevio.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgdevio.h 1.41.1.16 2014/07/18 11:01:41Z martin TRASH martin $ + * $Id: mbgdevio.h 1.47.1.4 2019/10/22 16:03:18Z martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,24 +10,48 @@ * * ----------------------------------------------------------------------- * $Log: mbgdevio.h $ - * Revision 1.41.1.16 2014/07/18 11:01:41Z martin - * Revision 1.41.1.15 2014/07/16 15:19:57 martin - * Revision 1.41.1.14 2014/07/16 13:06:39 martin - * Revision 1.41.1.13 2014/07/14 15:42:49 martin - * Revision 1.41.1.12 2014/06/26 12:24:22 martin - * Revision 1.41.1.11 2014/05/27 08:22:20Z martin - * Revision 1.41.1.10 2014/05/26 16:02:13 martin - * Revision 1.41.1.9 2014/05/23 12:40:19 martin - * Revision 1.41.1.8 2014/05/23 09:24:08 martin - * gpio and xmr functions. - * Revision 1.41.1.7 2014/04/23 15:42:59 martin - * Revision 1.41.1.6 2014/04/22 15:27:47 martin - * Revision 1.41.1.5 2014/04/22 13:29:18 martin - * Revision 1.41.1.4 2014/03/28 10:23:24 martin - * Revision 1.41.1.3 2014/03/05 10:38:29 martin - * Windows.h is now included in mbg_tgt.h. - * Revision 1.41.1.2 2014/01/31 14:45:35Z martin - * Revision 1.41.1.1 2013/12/12 11:24:16 martin + * Revision 1.47.1.4 2019/10/22 16:03:18Z martin + * *** empty log message *** + * Revision 1.47.1.3 2019/07/31 15:40:28 martin + * Doxygen changes. + * Revision 1.47.1.2 2019/05/24 14:51:10 martin + * Updated function prototypes. + * Revision 1.47.1.1 2019/05/03 13:24:11 martin + * Revision 1.47 2018/11/22 14:27:05Z martin + * Fixed pointer size problems in a mixed 32/64 bit Linux environment. + * Removed obolete preprocessor symbol MBG_USE_KERNEL_DRIVER + * and use new global symbol MBG_TGT_USE_IOCTL instead. + * Revision 1.46 2018/11/14 12:24:40 martin + * Renamed a preprocessor symbol to avoid a name clash. + * Revision 1.45 2018/09/21 08:59:17 martin + * New version code 0x0308, compatibility version still 0x0210. + * Account for a renamed library function. + * Updated function prototypes. + * Revision 1.44 2018/08/07 15:09:25Z martin + * New version code 0x0370, compatibility version still 0x0210. + * Revision 1.43 2018/07/05 08:50:48 martin + * Added missing linkage attribute for mbg_open_device(). + * Reworked handling of IOCTL return codes. + * Modified test if cpu_set_t and associated definitions are available. + * Use standard errno conversion functions. + * Removed usage of obsolete symbol MBGDEVIO_SIMPLE. + * Updated function prototypes. + * Revision 1.42 2017/07/05 15:20:32 martin + * New MBGDEVIO_VERSION 0x0400, compatibility version unchanged. + * Account for MBG_ERROR_CODES returned by the ioctl functions. + * New type MBG_DEV_FN used for device file names, formerly often + * referred to as 'hardware ID'. + * New type MBG_DEV_NAME used for unique device names, composed of + * device type name and serial number appended after an underscore. + * Renamed and reworked list handling for device lists. + * Use functions from new module timeutil. + * windows.h is now included in mbg_tgt.h. + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. + * Account for PCPS_HRT_BIN_FRAC_SCALE renamed to MBG_FRAC32_UNITS_PER_SEC. + * Fixed macro definition syntax to avoid clang compiler warnings. + * Exclude mbg_chk_tstamp64_leap_sec() for BC builds for now. + * Lots of new doxygen comments and groups. + * Updated function prototypes. * Revision 1.41 2013/09/26 08:54:54 martin * Defined thread function type MBG_THREAD_FNC. * Defined check-if-supported function type MBG_CHK_SUPP_FNC. @@ -55,7 +79,7 @@ * Made xhrt leap second check an inline function. * Fixed macro to avoid compiler warning. * Revision 1.39 2009/12/15 15:34:59Z daniel - * Support reading the raw IRIG data bits for firmware versions + * Support reading the raw IRIG data bits for firmware versions * which support this feature. * Revision 1.38.1.2 2009/12/10 09:58:53Z daniel * Revision 1.38.1.1 2009/12/10 09:45:29Z daniel @@ -151,11 +175,11 @@ * PC high resolution timer cycles. * Updated function prototypes. * Revision 1.9 2003/06/19 08:50:05Z martin - * Definition of MBGDEVIO_VERSION number to allow DLL + * Definition of MBGDEVIO_VERSION number to allow DLL * API version checking. * Replaced some defines by typedefs. * Renamed USE_DOS_TSR to MBG_USE_DOS_TSR. - * New preprocessor symbol MBG_USE_KERNEL_DRIVER which + * New preprocessor symbol MBG_USE_KERNEL_DRIVER which * is defined only for targets which use IOCTLs. * Don't include pcps_dos.h here. * Updated function prototypes. @@ -193,20 +217,28 @@ #include <mbg_tgt.h> #include <mbg_arch.h> +#include <cfg_hlp.h> +#include <timeutil.h> #include <mbgmutex.h> #include <mbgerror.h> #include <mbggeo.h> #include <pcpsdev.h> #include <pci_asic.h> #include <use_pack.h> + #include <time.h> +#include <stdio.h> +#include <errno.h> -#define MBGDEVIO_VERSION 0x0307 +#define MBGDEVIO_VERSION 0x0308 #define MBGDEVIO_COMPAT_VERSION 0x0210 -#define MBG_MAX_DEVICES 8 + +#if !defined( SUPP_SYN1588_USR_SPC ) + #define SUPP_SYN1588_USR_SPC 1 +#endif #if defined( MBG_TGT_WIN32 ) @@ -222,10 +254,7 @@ #define MBGDEVIO_HAVE_THREAD_AFFINITY 1 #endif - #define MBG_USE_KERNEL_DRIVER 1 - #define MBGDEVIO_RET_VAL DWORD - #define _mbgdevio_cnv_ret_val( _v ) (_v) #elif defined( MBG_TGT_LINUX ) @@ -240,7 +269,6 @@ // target envionment. Otherwise thread support is disabled // as per default. - #define MBG_USE_KERNEL_DRIVER 1 #include <sys/ioctl.h> #include <fcntl.h> #include <sched.h> @@ -251,14 +279,11 @@ #elif defined( MBG_TGT_BSD ) - #define MBG_USE_KERNEL_DRIVER 1 #include <sys/ioctl.h> #include <fcntl.h> #elif defined( MBG_TGT_OS2 ) - #define MBG_USE_KERNEL_DRIVER 1 - #elif defined( MBG_TGT_QNX_NTO ) #include <sys/types.h> @@ -282,7 +307,9 @@ #endif -#if defined( MBG_USE_KERNEL_DRIVER ) +#if MBG_TGT_USE_IOCTL + + #include <mbgioctl.h> #include <stdlib.h> #include <string.h> @@ -290,10 +317,6 @@ #endif -#if defined( MBG_TGT_POSIX ) - #define MBG_HAS_UNIX_IOCTL 1 -#endif - #if !defined( MBGDEVIO_XHRT_API ) #define MBGDEVIO_XHRT_API 0 #endif @@ -306,8 +329,16 @@ #define MBGDEVIO_HAVE_THREAD_AFFINITY 0 #endif +#if ( 0 && defined( DEBUG ) ) + #define DEBUG_IOCTL_CALLS 1 +#else + #define DEBUG_IOCTL_CALLS 0 +#endif + + #ifdef _MBGDEVIO #define _ext + #define _DO_INIT #else #define _ext extern #endif @@ -321,16 +352,11 @@ #endif -// If MBGDEVIO_SIMPLE != 0 then some complex configuration -// API calls are excluded from build, which would otherwise -// require some additional mbglib modules to be linked -// to the application. -#if !defined( MBGDEVIO_SIMPLE ) - #define MBGDEVIO_SIMPLE 0 +#ifdef __cplusplus +extern "C" { #endif - -#if defined( MBG_USE_KERNEL_DRIVER ) +#if MBG_TGT_USE_IOCTL // TODO should we use a different symbol to control this? typedef MBG_HANDLE MBG_DEV_HANDLE; @@ -351,27 +377,46 @@ #if !defined( _mbgdevio_cnv_ret_val ) - #define _mbgdevio_cnv_ret_val( _v ) \ - ( ( (_v) < 0 ) ? (_v) : MBG_SUCCESS ) + #define _mbgdevio_cnv_ret_val( _v ) (_v) #endif -#define _mbgdevio_vars() \ - MBGDEVIO_RET_VAL rc +/** + * @brief A string that can take a device file name + * + * The format of the device file name depends on the type of + * operating system. + * + * On Linux and similar systems this is something like + * a regular file name with an index number appended, + * e.g. "/dev/mbgclock0". See ::MBGCLOCK_DEV_FN_BASE. + * + * Under Windows this is a complex string composed of GUIDs, + * bus-specific vendor and device ID numbers, etc., which can't + * easily be handled manually. + */ +typedef char MBG_DEV_FN[260]; // Conforming to MAX_PATH in Windows + -#define _mbgdevio_ret_val \ - _mbgdevio_cnv_ret_val( rc ) +#if MBG_TGT_HAS_DEV_FN_BASE +#define MBGCLOCK_DEV_FN_BASE "/dev/mbgclock" +#define MBGCLOCK_DEV_FN_FMT MBGCLOCK_DEV_FN_BASE "%i" +_ext const char mbg_dev_fn_base[] +#ifdef _DO_INIT + = MBGCLOCK_DEV_FN_BASE +#endif +; + +_ext const char mbg_dev_fn_fmt[] +#ifdef _DO_INIT + = MBGCLOCK_DEV_FN_FMT +#endif +; + +#endif -/** - * @brief A string buffer for a unique device ID - * - * The unique ID is made up of the device model name - * and its serial number, i.e. [model_name]_[serial_number] - * E.g.: "GPS170PCI_028210040670" - */ -typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; // Definitions specific to the target OS @@ -381,7 +426,11 @@ typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; #define MBG_PROCESS_ID pid_t #define _mbg_get_current_process() 0 - #if defined( __cpu_set_t_defined ) + // __cpu_set_t_defined used to be defined by GNU's glibc. + // However, at least with glibc-2.26 this doesn't seem to be + // the case anymore, so we test alternatively if CPU_SETSIZE + // is defined. + #if defined( __cpu_set_t_defined ) || defined( CPU_SETSIZE ) #define MBG_CPU_SET cpu_set_t #define MBG_CPU_SET_SIZE CPU_SETSIZE #define _mbg_cpu_clear( _ps ) CPU_ZERO( (_ps) ) @@ -415,12 +464,9 @@ typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; #if !defined( MBG_TGT_WIN32 ) - - #define FILETIME int // just a dummy to avoid build errors - + #define FILETIME int // just a dummy to avoid build errors #endif - #if !defined( MBG_PROCESS_ID ) #define MBG_PROCESS_ID int #endif @@ -442,7 +488,7 @@ typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; #endif #if !defined( _mbg_cpu_set ) - #define _mbg_cpu_set( _i, _ps ) ( *(_ps) |= ( 1UL << (_i) ) ) + #define _mbg_cpu_set( _i, _ps ) ( *(_ps) |= ( (MBG_CPU_SET) 1UL << (_i) ) ) #endif #if !defined( _mbg_cpu_isset ) @@ -471,24 +517,57 @@ typedef char MBG_HW_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; #endif + +/** + * @brief A generic thread info structure + */ typedef struct { MBG_THREAD_ID thread_id; #if defined( MBG_TGT_WIN32 ) HANDLE exit_request; #endif + } MBG_THREAD_INFO; -typedef MBG_THREAD_FNC_RET_VAL (MBG_THREAD_FNC_ATTR *MBG_THREAD_FNC)(void *); +/** + * @brief A generic type of a thread function + */ +typedef MBG_THREAD_FNC_RET_VAL MBG_THREAD_FNC_ATTR MBG_THREAD_FNC( void * ); + + + +/** + * @brief A structure holding a time stamp / cycles count pair + * + * This can be used to extrapolate the current time from the current + * system cycles count. + * + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * @see @ref mbg_xhrt_poll_group + */ typedef struct { - PCPS_HR_TIME_CYCLES htc; - uint64_t pcps_hr_tstamp64; + PCPS_HR_TIME_CYCLES htc; ///< Cycles count associated with the time stamp + uint64_t pcps_hr_tstamp64; ///< Time stamp read from a device + } MBG_XHRT_VARS; + +/** + * @brief A status structure provided by the time polling thread function + * + * This can be used to get information from the poll thread function + * and extrapolate the current time from the current system cycles count. + * + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * @see @ref mbg_xhrt_poll_group + */ typedef struct { MBG_XHRT_VARS vars; @@ -498,13 +577,25 @@ typedef struct int sleep_ms; MBG_CRIT_SECT crit_sect; MBG_DEV_HANDLE dh; + } MBG_XHRT_INFO; + +/** + * @brief A structure used to control a poll thread function + * + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * @see ::mbg_xhrt_poll_thread_create + * @see ::mbg_xhrt_poll_thread_stop + * @see @ref mbg_xhrt_poll_group + */ typedef struct { MBG_XHRT_INFO xhrt_info; MBG_THREAD_INFO ti; + } MBG_POLL_THREAD_INFO; @@ -515,44 +606,257 @@ typedef struct * Match modes to determine how to proceed if a device with * particular model type and serial number has not been detected. */ -enum MBG_MATCH_MODE +enum MBG_MATCH_MODES { MBG_MATCH_ANY, ///< use the next device available on the system MBG_MATCH_MODEL, ///< use the next available device of the same type MBG_MATCH_EXACTLY, ///< use only exactly the excat matching device, otherwise fail - N_MBG_MATCH_MODE ///< number of known modes + N_MBG_MATCH_MODES ///< number of known modes }; -typedef struct _MBG_DEVICE_LIST +/** + * @brief An entry for a list of device file names + * + * Applications should consider this type as opaque, + * and must not rely on the type, number, and order of + * the structure members. + */ +typedef struct _MBG_DEV_FN_LIST_ENTRY MBG_DEV_FN_LIST_ENTRY; + + +/** + * @brief The structure behind the ::MBG_DEV_FN_LIST_ENTRY type + * + * Applications should consider this structure as opaque, + * and must not rely on the type, number, and order of + * the structure members. + * + * The definition is still in the header file since it + * is still required by some Windows-specific code. + */ +struct _MBG_DEV_FN_LIST_ENTRY { - char *device_path; /**< Hardware ID depending on the calling function */ - struct _MBG_DEVICE_LIST *next; + char *dev_fn_ptr; ///< Address of an OS-specific device file name + ///< that can be used with an OS-specific open call. + MBG_DEV_FN_LIST_ENTRY *next; +}; -} MBG_DEVICE_LIST; +/** + * @brief An entry for a list of device names + * + * Applications should consider this type as opaque, + * and must not rely on the type, number, and order of + * the structure members. + * + * @see ::mbg_find_devices_with_names + * @see ::mbg_free_device_name_list + */ +typedef struct _MBG_DEV_NAME_LIST_ENTRY MBG_DEV_NAME_LIST_ENTRY; -typedef struct _MBG_DEVICENAME_LIST + +/** + * @brief The structure behind the ::MBG_DEV_NAME_LIST_ENTRY type + * + * Applications should actually consider this structure as opaque, + * and must not rely on the type, number, and order of + * the structure members. + * + * The definition is still in the header file since it is still + * used by some Windows-specific code. + */ +struct _MBG_DEV_NAME_LIST_ENTRY { - char device_name[40]; /**< readable name */ - struct _MBG_DEVICENAME_LIST *next; + char dev_name[40]; ///< Readable device name (Should be ::MBG_DEV_NAME, which is smaller, though) + MBG_DEV_NAME_LIST_ENTRY *next; +}; -} MBG_DEVICENAME_LIST; /** - * @brief Type of functions to check if a feature is supported + * @defgroup mbgdevio_open_fncs API functions that can be used to open a device + * + * Each of these functions can be used to open a device to obtain a valid + * ::MBG_DEV_HANDLE handle which can be used with subsequent API calls to + * access the particular device. + * + * If the device fails to be opened then each of these functions returns + * ::MBG_INVALID_DEV_HANDLE, and an OS-specific "last error" code is set + * accordingly. The caller can then use ::mbg_get_last_error immediately + * to retrieve the OS-specific error code, convert it, and return the + * associated Meinberg-specific error code. See @ref MBG_ERROR_CODES. + * + * Operating systems maintain a list of devices that are currently + * present in a system. The function ::mbg_open_device expects a number + * that is used as an index to this list. If only a single supported device + * is present then index 0 can always be used to open that device. + * + * The function ::mbg_find_devices can be used to retrieve the number of + * devices statically present in the system, and the highest index number + * that can be used is the number of devices - 1. + * + * In a plug-and-play system the device list maintained by the operating + * system may change over time, for example if a USB device is plugged in + * or out during operation. In this case index numbers may change, and may + * not always refer to the same device. + * + * So the function ::mbg_open_device_by_name can be used instead to open + * a specific device identified by model name and optionally serial number. + * See ::MBG_DEV_NAME for the format of such device name. + * + * If a list of unique device names is required e.g. to set up a + * device selection dialog in a GUI application then the function + * ::mbg_find_devices_with_names can be used to allocate and set up + * such a list. When the list has been evaluated and isn't needed + * anymore then ::mbg_free_device_name_list should be called to free + * the allocated memory. + * + * Inside the operating system the device is always identified by a + * device file name which can be used internally with an OS-specific + * "open" function, e.g. "open" on POSIX systems, or ""CreateFile" + * on Windows. + * + * While the device file name is a complex string under Windows, + * under Linux and similar systems this is just a device node name + * like "/dev/mbgclock0" which can easily be used to specify a + * particular device. See ::MBG_DEV_FN. + * + * On such systems the function ::mbg_open_device_by_dev_fn can be used + * to open a device specified by a device file name. + * + * @see ::mbg_open_device + * @see ::mbg_find_devices + * @see ::mbg_open_device_by_name + * @see ::mbg_find_devices_with_names + * @see ::mbg_open_device_by_dev_fn + * @see ::mbg_close_device */ -typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh, int *p ); -/* function prototypes: */ +/** + * @defgroup mbgdevio_hr_time_fncs API functions reading high resolution time, plus status + * + * These functions return a high resolution time, including status flags and + * local time offset according to the time zone configuration on the device. + * + * The API call ::mbg_chk_dev_has_hr_time checks if these functions are supported + * by a device. + * + * Due to the extended information returned to the caller these function + * require interaction with the on-board microcontroller, and thus take + * longer to execute than the @ref mbgdevio_fast_timestamp_fncs. + * + * <b>Note:</b> These API calls provides better accuracy and higher resolution + * than the the standard functions in @ref mbgdevio_legacy_time_fncs. + * + * The ::mbg_get_hr_time function doesn't account for the latency + * which is introduced when accessing the board. + * + * The ::mbg_get_hr_time_cycles and ::mbg_get_hr_time_comp calls + * provide ways to account for and/or compensate the latency. + * + * @see ::mbg_chk_dev_has_hr_time + * @see ::mbg_get_hr_time + * @see ::mbg_get_hr_time_cycles + * @see ::mbg_get_hr_time_comp + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ + + +/** + * @defgroup mbgdevio_fast_timestamp_fncs Fast API functions reading high resolution timestamps, but no status + * + * These functions are fast, but return only the UTC time. No status flags, + * no time zone offset. The time stamps are read from a latched counter chain + * in the PCI chip set, so this is only supported by cards whose chip set supports this. + * + * @see ::mbg_chk_dev_has_fast_hr_timestamp + * @see ::mbg_get_fast_hr_timestamp + * @see ::mbg_get_fast_hr_timestamp_cycles + * @see ::mbg_get_fast_hr_timestamp_comp + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ + + +/** + * @defgroup mbgdevio_legacy_time_fncs Legacy API functions to read the time + * + * These functions are supported by all devices, but return time only + * as a ::PCPS_TIME structure, which provides local time according to the + * local time zone configured on the device, and with 10 ms resolution only. + * + * <b>Note:</b> The @ref mbgdevio_hr_time_fncs or @ref mbgdevio_fast_timestamp_fncs + * should be used preferably, if the device supports these. + * + * @see ::mbg_get_time + * @see ::mbg_get_time_cycles + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + */ + + +/** + * @defgroup mbgdevio_chk_supp_fncs mbgdevio functions used to check if a particular feature is supported + * @ingroup chk_supp_fncs + * + * These functions can be used to check if a device supports a particular feature. + * + * ::MBG_SUCCESS is returned if the requested feature is supported, + * ::MBG_ERR_NOT_SUPP_BY_DEV if the feature is not supported, or one of the other + * @ref MBG_ERROR_CODES is returned if an error occurred when trying to determine + * if the feature is supported, e.g. if an IOCTL call failed for some reason. + * + * @see ::MBG_CHK_SUPP_FNC + */ + + +/** + * @defgroup mbgdevio_chk_supp_fncs_deprecated Deprecated mbgdevio functions to check if a particular feature is supported + * @ingroup chk_supp_fncs + * + * @deprecated These functions are deprecated. Use the @ref mbgdevio_chk_supp_fncs preferably. + * + * These are the original functions that were introduced to check if a device supports + * a particular feature. The functions are deprecated, but will be kept for compatibility. + * + * The functions return ::MBG_SUCCESS if the information could be retrieved with out error, + * and an error code otherwise, e.g. if the IOCTL call itself failed. + * + * Only in case of success an integer variable the address of which has to be passed to the + * function is set to 1 or 0 depending on whether the requested feature is supported, or not. + * So the calling application always has to check 2 values after such a function has been called. + * + * To make applications simpler the @ref mbgdevio_chk_supp_fncs have been introduced instead, + * which can be used in a much easier way. + * + * @see @ref mbgdevio_chk_supp_fncs + */ + + + +/** + * @defgroup mbg_xhrt_poll_group Extrapolation of high resolution time stamps + * + * ::TODO + */ + + + +/** + * @brief The type of functions to check if a feature is supported + * + * @ingroup mbgdevio_chk_supp_fncs + * @see @ref mbgdevio_chk_supp_fncs + */ +typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh ); + + -#ifdef __cplusplus -extern "C" { -#endif /* ----- function prototypes begin ----- */ @@ -560,7 +864,7 @@ extern "C" { /* by MAKEHDR, do not remove the comments. */ /** - * @brief Get the version number of the precompiled DLL/shared object library + * @brief Get the version number of the precompiled DLL/shared object library. * * If this library is used as a DLL/shared object library then the version * number can be checked to see if the header files which are actually used @@ -568,7 +872,7 @@ extern "C" { * been used to build the library, and thus the API function are called * in the correct way. * - * @return the version number + * @return The version number * * @see ::mbgdevio_check_version * @see ::MBGDEVIO_VERSION defined in mbgdevio.h @@ -576,7 +880,7 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbgdevio_get_version( void ) ; /** - * @brief Check if the DLL/shared library is compatible with a given version + * @brief Check if the DLL/shared library is compatible with a given version. * * If this library is used as a DLL/shared object library then the version * number can be checked to see if the header files which are actually used @@ -587,7 +891,7 @@ extern "C" { * @param[in] header_version Version number to be checked, should be ::MBGDEVIO_VERSION * from the mbgdevio.h file version used to build the application * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE * * @see ::mbgdevio_get_version * @see ::MBGDEVIO_VERSION defined in mbgdevio.h @@ -595,94 +899,1954 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbgdevio_check_version( int header_version ) ; /** - * @brief Open a device by index, starting from 0 + * @brief Check if a device supports the ::RECEIVER_INFO structure and related calls. + * + * Very old devices may not provide a ::RECEIVER_INFO structure. + * The ::mbg_setup_receiver_info call should be used preferably to set up + * a ::RECEIVER_INFO for a device. That function uses this call to determine + * whether a ::RECEIVER_INFO can be read directly from a device, or sets up + * a default structure using default values depending on the device type. + * + * @note This function should be preferred over ::mbg_dev_has_receiver_info, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_setup_receiver_info + * @see ::mbg_get_gps_receiver_info + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_receiver_info( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports large configuration data structures. + * + * Such structures have been introduced with the first Meinberg GPS receivers. + * Mostly all configuration structures are large data structures, and mostly all + * current devices support this, but some old devices may not. + * + * @note This function should be preferred over ::mbg_dev_has_gps_data, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_gps_data( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::mbg_generic_io API call. + * + * <b>Warning</b>: This call is for debugging purposes and internal use only! + * + * @note This function should be preferred over ::mbg_dev_has_generic_io, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_generic_io + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_generic_io( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::mbg_get_asic_version API call. + * + * If ::mbg_get_asic_version is supported, or not, depends on + * the bus interface chip assembled on the device. + * + * @note This function should be preferred over ::mbg_dev_has_asic_version, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_asic_version + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_asic_version( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::mbg_get_asic_features call. + * + * If ::mbg_get_asic_features is supported, or not, depends on + * the bus interface chip assembled on the device. + * + * @note This function should be preferred over ::mbg_dev_has_asic_features, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_asic_features + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_asic_features( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides eXtended Multi Ref (XMR) inputs. + * + * Devices providing XMR inputs can receive or decode different timing + * signals in parallel, and the supported sources can be prioritized. + * + * @note This function should be preferred over ::mbg_dev_has_xmr, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_xmr_instances + * @see ::mbg_get_gps_all_xmr_status + * @see ::mbg_get_gps_all_xmr_info + * @see ::mbg_set_gps_xmr_settings_idx + * @see ::mbg_get_xmr_holdover_status + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_xmr( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if the device is connected via the ISA bus + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the device is connected via the ISA bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_isa( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if the device is connected via the MCA bus + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the device is connected via the MCA bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_mca( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if the device is connected via the PCI bus + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the device is connected via the PCI bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if the device is connected via the PCI Express bus + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the device is connected via the PCI Express bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_pci_express( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if the device is connected via the USB bus + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the device is connected via the USB bus, + * else ::MBG_ERR_NOT_SUPP_BY_DEV + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_usb( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device is a GPS receiver. + * + * The function also returns ::MBG_SUCCESS for GNSS receivers + * which can track GPS satellites beside other GNSS systems. + * + * A pure GPS receiver is not considered a GNSS receiver, but + * each of Meinberg's GNSS receivers is also a GPS receiver. + * + * @note This function should be preferred over ::mbg_dev_is_gps, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_gps( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device is a GNSS receiver. + * + * This is usually the case if a device supports reception of + * different satellite systems, e.g. GPS, Glonass, Galileo, etc. + * + * A pure GPS receiver is not considered a GNSS receiver, but + * each of Meinberg's GNSS receivers is also a GPS receiver. + * + * @note This function should be preferred over ::mbg_dev_is_gnss, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_gps_gnss_mode_info + * @see ::mbg_set_gps_gnss_mode_settings + * @see ::mbg_get_gps_all_gnss_sat_info + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_gnss( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device is a DCF77 receiver. + * + * Beside standard DCF77 receivers which receive the legacy AM signal + * there are also PZF receivers which can decode the pseudo-random phase + * modulation and thus yield a higher accuracy. See ::mbg_chk_dev_has_pzf. + * + * @note This function should be preferred over ::mbg_dev_is_dcf, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_dcf( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports demodulation of the DCF77 PZF code + * + * Beside the enhanced PZF correlation receivers which decode the DCF77's + * pseudo-random phase modulation to yield a better accuracy there are also + * legacy DCF77 receivers which just decode the standard AM signal. + * See ::mbg_chk_dev_is_dcf. + * + * @note This function should be preferred over ::mbg_dev_has_pzf, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_has_corr_info + * @see ::mbg_chk_dev_has_tr_distance + * @see ::mbg_chk_dev_is_dcf + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_pzf( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device is a MSF receiver + * + * @note This function should be preferred over ::mbg_dev_is_msf, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_msf( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device is a WWVB receiver + * + * @note This function should be preferred over ::mbg_dev_is_wwvb, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_wwvb( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device is a JJY receiver. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_jjy( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device is any long wave signal receiver + * + * Long wave receivers include e.g. DCF77, MSF, WWVB, or JJY. + * + * @note This function should be preferred over ::mbg_dev_is_lwr, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_is_dcf + * @see ::mbg_chk_dev_is_msf + * @see ::mbg_chk_dev_is_wwvb + * @see ::mbg_chk_dev_is_jjy + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_lwr( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device is a time code receiver (TCR, IRIG or similar) + * + * @note This function should be preferred over ::mbg_dev_is_irig_rx, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_irig_rx_info + * @see ::mbg_set_irig_rx_settings + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_has_irig +*/ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_is_tcr( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports simple LAN interface API calls + * + * @note This function should be preferred over ::mbg_dev_has_lan_intf, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_lan_if_info + * @see ::mbg_get_ip4_state + * @see ::mbg_get_ip4_settings + * @see ::mbg_set_ip4_settings + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_lan_intf( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports PTP configuration/status calls + * + * @note This function should be preferred over ::mbg_dev_has_ptp, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_all_ptp_cfg_info + * @see ::mbg_get_ptp_state + * @see ::mbg_get_ptp_cfg_info + * @see ::mbg_set_ptp_cfg_settings + * @see ::mbg_chk_dev_has_ptp_unicast + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports PTP unicast feature/configuration + * + * Not all devices which support PTP do also support PTP Unicast. This API + * call checks if PTP Unicast is supported in addition to the standard + * PTP multicast. + * + * @note This function should be preferred over ::mbg_dev_has_ptp_unicast, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_all_ptp_cfg_info + * @see ::mbg_get_ptp_uc_master_cfg_limits + * @see ::mbg_get_all_ptp_uc_master_info + * @see ::mbg_set_ptp_uc_master_settings_idx + * @see ::mbg_get_ptp_state + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ptp_unicast( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the mbg_get_hr_time... functions + * + * @note This function should be preferred over ::mbg_dev_has_hr_time, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_hr_time + * @see ::mbg_get_hr_time_cycles + * @see ::mbg_get_hr_time_comp + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_hr_time( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the mbg_get_fast_hr_timestamp... calls + * + * @note This function should be preferred over ::mbg_dev_has_fast_hr_timestamp, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_fast_hr_timestamp_cycles + * @see ::mbg_get_fast_hr_timestamp_comp + * @see ::mbg_get_fast_hr_timestamp + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports configurable time scales. + * + * By default the devices return %UTC and/or local time. However, some cards + * can be configured to return raw GPS time or TAI instead. + * + * @note This function should be preferred over ::mbg_dev_has_time_scale, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_time_scale_info + * @see ::mbg_set_time_scale_settings + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_time_scale( MBG_DEV_HANDLE dh ) ; + + /* (Intentionally excluded from Doxygen) + * @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 ) ; + + /** + * @brief Check if a device supports the ::mbg_get_ucap_entries and ::mbg_get_ucap_event calls + * + * If the device doesn't support this but is a GPS card then the card provides + * a time capture FIFO buffer and the obsolete ::mbg_get_gps_ucap call can be used + * to retrieve entries from the FIFO buffer. + * + * @note This function should be preferred over ::mbg_dev_has_ucap, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_ucap_entries + * @see ::mbg_get_ucap_event + * @see ::mbg_clr_ucap_buff + * @see ::mbg_get_gps_ucap + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ucap( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::mbg_clr_ucap_buff call + * + * The ::mbg_clr_ucap_buff call can be used to clear a device's on-board + * time capture FIFO buffer, but the call may not be supported by some + * older GPS devices. + * + * @note This function should be preferred over ::mbg_dev_can_clr_ucap_buff, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_clr_ucap_buff + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports timezone configuration using the ::TZDL structure + * + * @note This function should be preferred over ::mbg_dev_has_tzdl, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_gps_tzdl + * @see ::mbg_set_gps_tzdl + * @see ::mbg_chk_dev_has_tz + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tzdl( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure + * + * @note This function should be preferred over ::mbg_dev_has_pcps_tzdl, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_pcps_tzdl + * @see ::mbg_set_pcps_tzdl + * @see ::mbg_chk_dev_has_tz + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type. + * + * @note This function should be preferred over ::mbg_dev_has_tzcode, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_tzcode + * @see ::mbg_set_tzcode + * @see ::mbg_chk_dev_has_tz + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tzcode( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports any kind of timezone configuration. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @note This function should be preferred over ::mbg_dev_has_tz, + * which has been deprecated. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_has_tzdl + * @see ::mbg_chk_dev_has_pcps_tzdl + * @see ::mbg_chk_dev_has_tzcode + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tz( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides either an IRIG input or output. + * + * @note This function should be preferred over ::mbg_dev_has_irig, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig_tx + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides a configurable IRIG output. + * + * @note This function should be preferred over ::mbg_dev_has_irig, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_irig_tx_info + * @see ::mbg_set_irig_tx_settings + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig + * @see @ref group_icode + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_tx( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::mbg_get_irig_ctrl_bits call + * + * @note This function should be preferred over ::mbg_dev_has_irig_ctrl_bits, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_irig_ctrl_bits + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::mbg_get_raw_irig_data call + * + * @note This function should be preferred over ::mbg_dev_has_raw_irig_data, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_raw_irig_data + * @see ::mbg_get_raw_irig_data_on_sec_change + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_raw_irig_data( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::mbg_get_irig_time call + * + * @note This function should be preferred over ::mbg_dev_has_irig_time, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_irig_time + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_irig_time( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides the level of its inputs signal + * + * This is useful to display the signal level of e.g. an IRIG or similar + * time code, or a long wave signal. + * + * @note This function should be preferred over ::mbg_dev_has_signal, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_signal( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides a modulation signal + * + * Modulation signals are e.g. the second marks provided by a long wave receiver. + * + * @note This function should be preferred over ::mbg_dev_has_mod, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_mod( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the "last sync time". + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_sync_time( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides the receiver position. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_rcvr_pos( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides the status of buffered variables. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_bvar_stat( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::mbg_get_ttm_time API call. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ttm_time( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides one or more serial ports. + * + * @note This function should only be used for legacy devices that + * don't provide a ::RECEIVER_INFO structure. + * Otherwise ::RECEIVER_INFO::n_com_ports should be checked to see + * if and how many serial ports are provided by the device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_serial( MBG_DEV_HANDLE dh ) ; + + /* (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 ) ; + + /** + * @brief Check if a device provides a programmable frequency synthesizer * - * @deprecated This function is deprecated, - * ::mbg_open_device_by_name should be used instead. + * @note This function should be preferred over ::mbg_dev_has_synth, + * which has been deprecated. * - * @note See comments for ::mbg_find_devices for details. + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * - * @param[in] device_index Index of the device, use 0 for the first device + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_synth + * @see ::mbg_set_synth + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_synth( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides GPIO signal inputs and/or outputs + * + * @note This function should be preferred over ::mbg_dev_has_gpio, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_gpio_cfg_limits + * @see ::mbg_get_gps_all_gpio_info + * @see ::mbg_set_gps_gpio_settings_idx + * @see ::mbg_get_gps_all_gpio_status + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_gpio( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports configuration of antenna cable length + * + * @note This function should be preferred over ::mbg_dev_has_cab_len, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_gps_ant_cable_len + * @see ::mbg_set_gps_ant_cable_len + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_cab_len( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides a configurable ref time offset + * + * This may be required to convert the received time to %UTC, if the input + * signal doesn't specify this (e.g. with most IRIG code formats). + * + * @note This function should be preferred over ::mbg_dev_has_ref_offs, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_ref_offs + * @see ::mbg_set_ref_offs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_ref_offs( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS. + * + * These structures contain optional settings, controlled by flags. + * See ::MBG_OPT_SETTINGS and associated definitions. + * + * @note This function should be preferred over ::mbg_dev_has_opt_flags, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_opt_info + * @see ::mbg_set_opt_settings + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_opt_flags( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device support reading/writing of UTC parameters. + * + * This API call checks if a device supports reading/writing a GPS %UTC + * parameter set via the PC bus. Reading/writing these parameters via the + * serial port using the Meinberg binary data protocol is supported by all + * Meinberg GPS and GNSS devices. + * + * The %UTC parameter set is usually received from the satellites' broadcasts + * and contains the current time offset between GPS time and UTC, plus information + * on a pending leap second event. + * + * It may be useful to overwrite them to do some tests, or for applications + * where a card is freewheeling. + * + * @note This function should be preferred over ::mbg_dev_has_utc_parm, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_utc_parm + * @see ::mbg_set_utc_parm + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_utc_parm( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports reading correlation info + * + * The PZF phase modulation decoded by DCF77 PZF receivers is decoded + * using a correlation approach, and optionally there's an API call + * supported which can be used to retrieve the correlation value + * and thus determine the quality of the input signal. + * + * @note This function should be preferred over ::mbg_dev_has_corr_info, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_get_corr_info + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_corr_info( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports configurable distance from transmitter + * + * The distance from transmitter parameter is used to compensate + * the RF propagation delay, mostly with long wave receivers. + * + * @note This function should be preferred over ::mbg_dev_has_tr_distance, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_get_tr_distance + * @see ::mbg_set_tr_distance + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_tr_distance( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides a debug status word to be read + * + * @note This function should be preferred over ::mbg_dev_has_debug_status, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_get_debug_status + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_debug_status( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device provides an on-board event log + * + * @note This function should be preferred over ::mbg_dev_has_evt_log, + * which has been deprecated. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + * @see ::mbg_clr_evt_log + * @see ::mbg_get_num_evt_log_entries + * @see ::mbg_get_first_evt_log_entry + * @see ::mbg_get_next_evt_log_entry + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_evt_log( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports bus level DAC control commands + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS if the requested feature is supported, ::MBG_ERR_NOT_SUPP_BY_DEV + * if not supported, or one of the other @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs + */ + _MBG_API_ATTR int _MBG_API mbg_chk_dev_has_dac_ctrl( MBG_DEV_HANDLE dh ) ; + + /** + * @brief Check if a device supports the ::RECEIVER_INFO structure and related calls + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_receiver_info preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_receiver_info + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_receiver_info" ) _MBG_API mbg_dev_has_receiver_info( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports large configuration data structures + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_gps_data preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_gps_data + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gps_data" ) _MBG_API mbg_dev_has_gps_data( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the ::mbg_generic_io API call + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_generic_io preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_generic_io + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_generic_io" ) _MBG_API mbg_dev_has_generic_io( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the ::mbg_get_asic_version call + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_asic_version preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_asic_version + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_asic_version" ) _MBG_API mbg_dev_has_asic_version( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the ::mbg_get_asic_features call. + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_asic_features preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_asic_features + * @see ::mbg_get_asic_features + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_asic_features" ) _MBG_API mbg_dev_has_asic_features( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device provides extended multi ref (XMR) inputs. + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_xmr preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_xmr + * @see @ref group_multi_ref_ext + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_xmr" ) _MBG_API mbg_dev_has_xmr( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports GNSS configuration + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_gnss preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_gnss + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gnss" ) _MBG_API mbg_dev_is_gnss( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device is a GPS receiver + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_gps preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_gps + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_gps" ) _MBG_API mbg_dev_is_gps( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device is a DCF77 receiver + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_dcf preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_dcf + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_dcf" ) _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports demodulation of the DCF77 PZF code + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_pzf preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_pzf + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pzf" ) _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device is a MSF receiver + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_msf preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_msf + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_msf" ) _MBG_API mbg_dev_is_msf( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device is a WWVB receiver + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_wwvb preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_wwvb + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_wwvb" ) _MBG_API mbg_dev_is_wwvb( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device is any long wave signal receiver + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_lwr preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_lwr + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_lwr" ) _MBG_API mbg_dev_is_lwr( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device provides a configurable IRIG input. + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_is_tcr preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_is_tcr + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_is_tcr" ) _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports simple LAN interface API calls + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_lan_intf preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_lan_intf + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_lan_intf" ) _MBG_API mbg_dev_has_lan_intf( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports PTP configuration/status calls + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ptp preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_ptp + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp" ) _MBG_API mbg_dev_has_ptp( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports PTP unicast feature/configuration + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ptp_unicast preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_ptp_unicast + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ptp_unicast" ) _MBG_API mbg_dev_has_ptp_unicast( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the HR_TIME functions + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_hr_time preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_hr_time + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_hr_time" ) _MBG_API mbg_dev_has_hr_time( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_fast_hr_timestamp preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_fast_hr_timestamp + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_fast_hr_timestamp" ) _MBG_API mbg_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports configurable time scales + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_time_scale preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_time_scale + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_time_scale" ) _MBG_API mbg_dev_has_time_scale( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports setting an event time + * + * @note This is only supported by some customized devices + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_event_time preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_event_time + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_event_time" ) _MBG_API mbg_dev_has_event_time( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the ::mbg_get_ucap_entries and ::mbg_get_ucap_event calls + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ucap preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_ucap + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ucap" ) _MBG_API mbg_dev_has_ucap( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the ::mbg_clr_ucap_buff call + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_can_clr_ucap_buff preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_can_clr_ucap_buff + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_can_clr_ucap_buff" ) _MBG_API mbg_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports timezone configuration using the ::TZDL structure + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tzdl preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_tzdl + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzdl" ) _MBG_API mbg_dev_has_tzdl( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_pcps_tzdl preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_pcps_tzdl + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_pcps_tzdl" ) _MBG_API mbg_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tzcode preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_tzcode + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tzcode" ) _MBG_API mbg_dev_has_tzcode( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports any kind of timezone configuration + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tz preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_tz + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tz" ) _MBG_API mbg_dev_has_tz( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device provides either an IRIG input or output + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_irig + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig" ) _MBG_API mbg_dev_has_irig( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device provides a configurable IRIG output + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_tx preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_irig_tx + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_tx" ) _MBG_API mbg_dev_has_irig_tx( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the ::mbg_get_irig_ctrl_bits call + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_ctrl_bits preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_irig_ctrl_bits + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_ctrl_bits" ) _MBG_API mbg_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the ::mbg_get_raw_irig_data call + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_raw_irig_data preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_raw_irig_data + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_raw_irig_data" ) _MBG_API mbg_dev_has_raw_irig_data( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the ::mbg_get_irig_time call + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_irig_time preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_irig_time + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_irig_time" ) _MBG_API mbg_dev_has_irig_time( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device provides the level of its inputs signal + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_signal preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_signal + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_signal" ) _MBG_API mbg_dev_has_signal( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device provides a modulation signal + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_mod preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_mod + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_mod" ) _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p ) ; + + /* (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 ) ; + + /** + * @brief Check if a device provides a programmable frequency synthesizer + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_synth preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_synth + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_synth" ) _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device provides GPIO signal inputs and/or outputs + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_gpio preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_gpio + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_gpio" ) _MBG_API mbg_dev_has_gpio( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports configuration of antenna cable length + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_cab_len preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_cab_len + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_cab_len" ) _MBG_API mbg_dev_has_cab_len( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device provides a configurable ref time offset + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_ref_offs preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_ref_offs + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_ref_offs" ) _MBG_API mbg_dev_has_ref_offs( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_opt_flags preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_opt_flags + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_opt_flags" ) _MBG_API mbg_dev_has_opt_flags( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device support reading/writing of ::UTC parameters + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_utc_parm preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_utc_parm + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_utc_parm" ) _MBG_API mbg_dev_has_utc_parm( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports reading correlation info + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_corr_info preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_corr_info + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_corr_info" ) _MBG_API mbg_dev_has_corr_info( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device supports configurable distance from transmitter + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_tr_distance preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_tr_distance + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_tr_distance" ) _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device provides a debug status word to be read + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_debug_status preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_debug_status + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_debug_status" ) _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Check if a device provides an on-board event log. + * + * @deprecated This function is deprecated, use ::mbg_chk_dev_has_evt_log preferably. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to an int which is updated if the API call succeeds. + * The flag is set != 0 if the requested feature is supported, else 0. + * + * @return ::MBG_SUCCESS on success, if *p has been updated, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_chk_supp_fncs_deprecated + * @see ::mbg_chk_dev_has_evt_log + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_chk_dev_has_evt_log" ) _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) ; + + /** + * @brief Create a device file name associated with an index number + * + * Create a system-specific device file name string, e.g. "/dev/mbgclock0" + * under Linux and similar systems, which can be used with the + * open() call on systems which support this, and is also appropriate for + * informational messages, e.g.when referring to a specific device. + * + * Under Windows a hardware ID string is required to open the device, + * and the Windows-specific function mbg_svc_get_device_path can be used + * get the hardware ID string associated with a specific device index + * for that purpose. + * + * However, the Windows hardware ID string is not appropriate for + * informational messages referring to a device, so this function + * can be used under Windows and other target systems that don't + * support simple device file names to create a generic string + * like "device #0". + * + * @param[out] s Pointer to the output buffer. + * @param[in] max_len Size of the output buffer. + * @param[in] dev_idx The device index number. + * + * @see mbg_svc_get_device_path under Windows + */ + _MBG_API_ATTR int _MBG_API mbg_dev_fn_from_dev_idx( char *s, int max_len, int dev_idx ) ; + + /** + * @brief Open a device by index number + * + * If the call fails then ::mbg_get_last_error should be called + * immediately to get the reason why. + * + * For details and similar functions see @ref mbgdevio_open_fncs. + * + * @param[in] dev_idx Device index number, starting from 0. * * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs */ - _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device( unsigned int device_index ) ; + _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device( int dev_idx ) ; /** - * @brief Get the number of supported devices installed on the computer. + * @brief Open a device specified by a device file name * - * @deprecated This function is deprecated, ::mbg_find_devices_with_names - * should be used instead. + * The format the device file name depends on the operating system. + * see ::MBG_DEV_FN. + * + * If the call fails then ::mbg_get_last_error should be called + * immediately to get the reason why. + * + * For details and similar functions see @ref mbgdevio_open_fncs. + * + * @param[in] dev_fn The device file name + * + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_FN + */ + _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_dev_fn( const char *dev_fn ) ; + + /** + * @brief Open a device specified by a device file name + * + * @deprecated This function is deprecated, use + * ::mbg_open_device_by_dev_fn preferably. + * + * The format the device file name depends on the operating system. + * see ::MBG_DEV_FN. + * + * If the call fails then ::mbg_get_last_error should be called + * immediately to get the reason why. + * + * For details and similar functions see @ref mbgdevio_open_fncs. + * + * @param[in] dev_fn The device file name, see ::MBG_DEV_FN * - * @note This function is out of date since it may not work - * correctly for Meinberg devices which are disconnected and reconnected - * while the system is running (e.g. USB devices). However, the function - * will be kept for compatibility reasons and works correctly if all - * Meinberg devices are connected at system boot and are not disconnected - * and reconnected during operation + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_FN + */ + _MBG_API_ATTR MBG_DEV_HANDLE _DEPRECATED_BY( "mbg_open_device_by_dev_fn" ) _MBG_API mbg_open_device_by_hw_id( const char *dev_fn ) ; + + /** + * @brief Get the number of devices installed on the computer + * + * The function ::mbg_find_devices_with_names should eventually + * be used preferafly. See @ref mbgdevio_open_fncs. * * @return The number of devices found * * @see ::mbg_find_devices_with_names + * @see ::mbg_open_device + * @see @ref mbgdevio_open_fncs */ _MBG_API_ATTR int _MBG_API mbg_find_devices( void ) ; /** - * @brief Allocate memory and set up a list of installed and supported devices. + * @brief Allocate memory and set up a list of installed and supported devices * - * This function should be used preferably instead of ::mbg_find_devices. + * Allocate and fill a list with the names of Meinberg devices currently + * present in the system. * - * @param[in] device_list Pointer to a linked list of type ::MBG_DEVICENAME_LIST - * with device names. The list will be allocated by this - * function and has to be freed after usage by calling - * ::mbg_free_device_name_list. - * @param[in] max_devices Maximum number of devices the function should look for - * (must not exceed ::MBG_MAX_DEVICES). + * This can be used e.g. to populate a device selection dialog + * in a configuration program. * - * @return number of present devices + * When the list is not used anymore it can be freed by calling + * ::mbg_free_device_name_list. + * + * @param[in] p_list Pointer to a linked list to be allocated. + * @param[in] max_devices Maximum number of devices to be searched for + * (must not exceed ::N_SUPP_DEV_BUS). + * + * @return The number of present devices * - * @see ::MBG_HW_NAME for the format of the unique names * @see ::mbg_free_device_name_list * @see ::mbg_find_devices + * @see ::MBG_DEV_NAME */ - _MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEVICENAME_LIST **device_list, int max_devices ) ; + _MBG_API_ATTR int _MBG_API mbg_find_devices_with_names( MBG_DEV_NAME_LIST_ENTRY **p_list, int max_devices ) ; /** - * @brief Free the memory allocated for a ::MBG_DEVICENAME_LIST. + * @brief Free the memory allocated for a list of ::MBG_DEV_NAME_LIST_ENTRY entries. * * The list may have been set up and allocated before * by ::mbg_find_devices_with_names. * - * @param[in,out] *list Linked list of type ::MBG_DEVICENAME_LIST + * @param[in,out] list Linked list of ::MBG_DEV_NAME_LIST_ENTRY entries. * * @see ::mbg_find_devices_with_names */ - _MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEVICENAME_LIST *list) ; + _MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEV_NAME_LIST_ENTRY *list ) ; + + /** + * @brief Split an ::MBG_DEV_NAME into the 'type name' and 'serial number' components + * + * See ::MBG_DEV_NAME for the possible formats of a device name. + * If no @p dev_name is passed then the destination buffers are set + * to empty strings. + * + * The complementary function ::snprint_dev_name can be used + * to generate a device name string. + * + * @param[in] dev_name The ::MBG_DEV_NAME string to be split up + * @param[out] type_name Output buffer for the type name part, e.g. a ::PCPS_CLOCK_NAME + * @param[in] type_name_size Size of the output buffer for the type name string + * @param[out] sernum Output buffer for the sernum part, e.g. a ::PCPS_SN_STR + * @param[in] sernum_size Size of the output buffer for the sernum string + * + * @see ::snprint_dev_name + * @see ::MBG_DEV_NAME + * @see ::MBG_DEV_NAME_FMT + */ + _MBG_API_ATTR void _MBG_API mbg_split_dev_name( const MBG_DEV_NAME dev_name, char *type_name, size_t type_name_size, char *sernum, size_t sernum_size ) ; /** - * @brief Return a handle to a device with a certain unique name. + * @brief Return a handle to a device with a particular device name * - * The names of the devices that are installed on the system can be retrieved by - * the function ::mbg_find_devices_with_names. + * See ::MBG_DEV_NAME for the possible formats of a device name. * - * This function should be used preferably instead of ::mbg_open_device. + * If the call fails then ::mbg_get_last_error should be called + * immediately to get the reason why. * - * @param[in] srch_name String with the unique name of the device to be opened - * @param[in] selection_mode One of the enum values of ::MBG_MATCH_MODE + * For details and similar functions see @ref mbgdevio_open_fncs. * - * @return On success, the function returns a handle to the device, otherwise ::MBG_INVALID_DEV_HANDLE + * @param[in] srch_name String with the ::MBG_DEV_NAME of a device to be opened + * @param[in] selection_mode One of the ::MBG_MATCH_MODES * - * @see ::MBG_HW_NAME for the format of the unique names - * @see ::MBG_MATCH_MODE - * @see ::mbg_find_devices_with_names + * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE + * + * @ingroup mbgdevio_open_fncs + * @see ::mbg_close_device + * @see @ref mbgdevio_open_fncs + * @see ::MBG_DEV_NAME + * @see ::MBG_MATCH_MODES */ - _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char *srch_name, int selection_mode ) //##++++ -; + _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const MBG_DEV_NAME srch_name, int selection_mode ) ; /** - * @brief Close a handle to a device and set the handle value to ::MBG_INVALID_DEV_HANDLE. + * @brief Close a device handle and set the handle value to ::MBG_INVALID_DEV_HANDLE * * @param[in,out] dev_handle Pointer to a Meinberg device handle + * + * @see @ref mbgdevio_open_fncs */ _MBG_API_ATTR void _MBG_API mbg_close_device( MBG_DEV_HANDLE *dev_handle ) ; @@ -690,31 +2854,35 @@ extern "C" { * @brief Read information about the driver handling a given device * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] *p A ::PCPS_DRVR_INFO structure to be filled up. + * @param[out] p A ::PCPS_DRVR_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_get_drvr_info( MBG_DEV_HANDLE dh, PCPS_DRVR_INFO *p ) ; /** * @brief Read detailed device information * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] *p A ::PCPS_DEV structure to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Address of a ::PCPS_DEV structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_get_device_info( MBG_DEV_HANDLE dh, PCPS_DEV *p ) ; /** * @brief Read the current state of the on-board ::PCPS_STATUS_PORT * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] *p A ::PCPS_STATUS_PORT value to be filled up + * This function is useful to read the device's status port which + * also includes the ::PCPS_ST_MOD bit reflecting the time code + * modulation of long wave receivers. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p A ::PCPS_STATUS_PORT value to be filled up * - * @see @ref group_status_port "bitmask" //##++++ + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see @ref group_status_port "bitmask" //### TODO check syntax */ _MBG_API_ATTR int _MBG_API mbg_get_status_port( MBG_DEV_HANDLE dh, PCPS_STATUS_PORT *p ) ; @@ -724,14 +2892,14 @@ extern "C" { * * <b>Warning</b>: This is for debugging purposes only! * The specialized API calls should be used preferably. - * A specific device may not support any command code. + * 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 buffer *p + * @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, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_generic_write * @see ::mbg_generic_read_gps @@ -741,110 +2909,111 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_generic_read( MBG_DEV_HANDLE dh, int cmd, void *p, int size ) ; /* (Intentionally excluded from Doxygen) - Generic read function which writes a GPS command code to a device - and reads a number of replied data to a generic buffer. - The macro _pcps_has_gps_data() or the API call mbg_dev_has_gps_data() - check whether this call is supported by a device. - - <b>Warning</b>: This is for debugging purposes only! - The specialized API calls should be used preferably. - A specific device may not support any GPS command code. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param cmd Can be any @ref PCPS_CMD_CODES "command code" supported by the device - @param *p Pointer to a buffer to be filled up - @param size Size of the buffer *p - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_gps_data + * 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 ) ; /* (Intentionally excluded from Doxygen) - Generic write function which writes a command code plus an - associated number of data bytes to a device. - - <b>Warning</b>: This is for debugging purposes only! - The specialized API calls should be used preferably. - A specific device may not support any command code. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param cmd Can be any @ref PCPS_CMD_CODES "command code" supported by the device - @param *p Pointer to a buffer to be written - @param size Size of the buffer *p - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * 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 ) ; /* (Intentionally excluded from Doxygen) - Generic write function which writes a GPS command code plus an - associated number of data bytes to a device. - The macro _pcps_has_gps_data() or the API call mbg_dev_has_gps_data() - check whether this call is supported by a device. - - <b>Warning</b>: This is for debugging purposes only! - The specialized API calls should be used preferably. - A specific device may not support any GPS command code. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param cmd Can be any @ref PCPS_CMD_CODES "command code" supported by the device - @param *p Pointer to a buffer to be written - @param size Size of the buffer *p - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_gps_data + * 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 ) ; /* (Intentionally excluded from Doxygen) - Write and/or read generic data to/from a device. - The macro _pcps_has_generic_io() or the API call mbg_dev_has_generic_io() - check whether this call is supported by a device. - - <b>Warning</b>: This call is for debugging purposes and internal use only! - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_generic_io + * Write and/or read generic data to/from a device. + * The function ::mbg_chk_dev_has_generic_io checks + * whether this call is supported by a device. + * + * <b>Warning</b>: This call is for debugging purposes and internal use only! + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_generic_io * @see ::mbg_generic_read * @see ::mbg_generic_write * @see ::mbg_generic_read_gps * @see ::mbg_generic_write_gps - */ + */ _MBG_API_ATTR int _MBG_API mbg_generic_io( MBG_DEV_HANDLE dh, int type, const void *in_p, int in_sz, void *out_p, int out_sz ) ; /** - * @brief Read a ::PCPS_TIME structure returning the current date/time/status. - - The returned time is local time according to the card's time zone setting, - with a resolution of 10 ms (i.e. 10ths of seconds). - - This call is supported by any device manufactured by Meinberg. - However, for higher accuracy and resolution the mbg_get_hr_time..() or - mbg_get_fast_hr_timestamp..() group of calls should be used preferably - if supported by the device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @brief Read a ::PCPS_TIME structure returning the current date/time/status + * + * The returned time is local time according to the card's time zone setting, + * with a resolution of 10 ms (i.e. 10ths of seconds) only. + * + * This call is supported by any device manufactured by Meinberg. + * However, for higher accuracy and resolution the @ref mbgdevio_hr_time_fncs or + * the @ref mbgdevio_fast_timestamp_fncs group of calls should be used preferably, + * if supported by the device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * + * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_hr_time * @see ::mbg_set_time * @see ::mbg_get_sync_time @@ -853,103 +3022,104 @@ extern "C" { /** * @brief Set the device's on-board clock to a given date and time. - - The macro _pcps_can_set_time() checks whether this call - is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_STIME structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * + * The macro ::_pcps_can_set_time checks whether + * this call is supported by a device. + * + * @todo Provide an API function replacing ::_pcps_can_set_time. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_STIME structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_time */ _MBG_API_ATTR int _MBG_API mbg_set_time( MBG_DEV_HANDLE dh, const PCPS_STIME *p ) ; /** - * @brief Read the time when the device has last recently synchronized. - - Fills a ::PCPS_TIME structure with the date/time/status reporting - when the device was synchronized the last time to its time source, - e.g. the DCF77 signal, the GPS satellites, or similar. - The macro _pcps_has_sync_time() or the API call mbg_dev_has_sync_time() - check whether this call is supported by a device. - - The macro _pcps_has_sync_time() checks whether this call - is supported by a device. - - <b>Note:</b> If that information is not available on the board then - the value of the returned ::PCPS_TIME::sec field is set to 0xFF. - The macro _pcps_time_is_read() can be used to check whether the - returned information is valid, or not available. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @brief Read the time when the device has last recently synchronized + * + * Fills a ::PCPS_TIME structure with the date/time/status reporting + * when the device was synchronized the last time to its time source, + * e.g. the DCF77 signal, the GPS satellites, or similar. + * + * The macro ::_pcps_has_sync_time checks whether + * this call is supported by a device. + * + * <b>Note:</b> If that information is not available on the board then + * the value of the returned ::PCPS_TIME::sec field is set to 0xFF. + * The macro ::_pcps_time_is_read can be used to check whether the + * returned information is valid, or "not set". + * + * @todo Provide an API function replacing ::_pcps_has_sync_time. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_time */ _MBG_API_ATTR int _MBG_API mbg_get_sync_time( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; /** - * @brief Wait until the next second change, then return current time. - - Returns time in a ::PCPS_TIME structure similar to mbg_get_time(). - - <b>Note:</b> This API call is supported under Windows only. - The call blocks until the kernel driver detects a second change - reported by the device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @brief Wait until the next second change, then return current time + * + * Returns time in a ::PCPS_TIME structure similar to ::mbg_get_time. * + * <b>Note:</b> This API call is supported under Windows only. + * The call blocks until the kernel driver detects a second change + * reported by the device. The accuracy of this call is limited + * to a few milliseconds. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_TIME structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_time */ _MBG_API_ATTR int _MBG_API mbg_get_time_sec_change( MBG_DEV_HANDLE dh, PCPS_TIME *p ) ; /** - * @brief Read the card's current time with high resolution, plus status. - - Fills up a ::PCPS_HR_TIME (High Resolution time) structure containing - the current %UTC time (seconds since 1970), %UTC offset, and status. - The macro _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() - check whether this call is supported by a device. - - <b>Note:</b> This API call provides a higher accuracy and resolution - than mbg_get_time(). However, it does not account for the latency - which is introduced when accessing the board. - The mbg_get_hr_time_cycles() and mbg_get_hr_time_comp() calls - provide ways to account for and/or compensate the latency. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_HR_TIME structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @brief Read the card's current time with high resolution, including status * - * @see ::mbg_dev_has_hr_time - * @see ::mbg_get_time - * @see ::mbg_get_hr_time_cycles - * @see ::mbg_get_hr_time_comp + * Fills up a ::PCPS_HR_TIME (High Resolution time) structure containing + * the current %UTC time (seconds since 1970), %UTC offset, and status. + * + * The API call ::mbg_chk_dev_has_hr_time checks whether + * this call is supported by a device. + * + * For details see @ref ::mbgdevio_hr_time_fncs + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_hr_time_fncs + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs */ _MBG_API_ATTR int _MBG_API mbg_get_hr_time( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; /* (Intentionally excluded from Doxygen ) - Write a high resolution time stamp ::PCPS_TIME_STAMP to a device - to configure a %UTC time when the clock shall generate an event. - The macro _pcps_has_event_time() or the API call mbg_dev_has_event_time() - check whether this call is supported by a device. - - <b>Note:</b> This is only supported by some special firmware. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * Write a high resolution time stamp ::PCPS_TIME_STAMP to a device + * to configure a %UTC time when the clock shall generate an event. + * The API call ::mbg_chk_dev_has_event_time checks whether + * this call is supported by a device. * - * @see ::mbg_dev_has_event_time + * <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 ) ; @@ -960,13 +3130,13 @@ extern "C" { * API function ::mbg_get_serial_settings should be used instead * which fully supports the capabilities of current devices. * - * The macro ::_pcps_has_serial checks whether this call - * is supported by a device. + * The macro ::_pcps_has_serial checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[out] p Pointer to a ::PCPS_SERIAL structure to be filled up * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_serial_settings */ @@ -979,13 +3149,13 @@ extern "C" { * API function ::mbg_save_serial_settings should be used instead * which fully supports the capabilities of current devices. * - * The macro ::_pcps_has_serial checks whether this call - * is supported by a device. + * The macro ::_pcps_has_serial checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. * @param[in] p Pointer to a ::PCPS_SERIAL structure to be written * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_save_serial_settings */ @@ -993,23 +3163,23 @@ extern "C" { /** * @brief Read time zone/daylight saving configuration code from a device. - - The APIs using TZCODE are only supported by some simpler cards - and allow just a very basic configuration. - - The macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() - check whether this call is supported by a device. - - Other cards may support the mbg_get_pcps_tzdl() or mbg_get_gps_tzdl() - calls instead which allow for a more detailed configuration of the - time zone and daylight saving settings. - + * + * The APIs using ::TZCODE are only supported by some simpler cards + * and allow just a very basic configuration. + * + * The API call ::mbg_chk_dev_has_tzcode checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_get_pcps_tzdl or ::mbg_get_gps_tzdl + * calls instead which allow for a more detailed configuration of the + * time zone and daylight saving settings. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZCODE structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::PCPS_TZCODE structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_tzcode + * @see ::mbg_chk_dev_has_tzcode * @see ::mbg_set_tzcode * @see ::mbg_get_pcps_tzdl * @see ::mbg_get_gps_tzdl @@ -1018,23 +3188,23 @@ extern "C" { /** * @brief Write time zone/daylight saving configuration code to a device. - - The APIs using TZCODE are only supported by some simpler cards - and allow just a very basic configuration. - - The macro _pcps_has_tzcode() or the API call mbg_dev_has_tzcode() - check whether this call is supported by a device. - - Other cards may support the mbg_set_pcps_tzdl() or mbg_set_gps_tzdl() - calls instead which allow for a more detailed configuration of the - time zone and daylight saving settings. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZCODE structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES * - * @see ::mbg_dev_has_tzcode + * The APIs using ::TZCODE are only supported by some simpler cards + * and allow just a very basic configuration. + * + * The API call ::mbg_chk_dev_has_tzcode checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_set_pcps_tzdl or ::mbg_set_gps_tzdl + * calls instead which allow for a more detailed configuration of the + * time zone and daylight saving settings. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_TZCODE structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_tzcode * @see ::mbg_get_tzcode * @see ::mbg_set_pcps_tzdl * @see ::mbg_set_gps_tzdl @@ -1043,127 +3213,129 @@ extern "C" { /** * @brief Read time zone/daylight saving parameters from a device. - - This function fills up a ::PCPS_TZDL structure which supports a more - detailed configuration of time zone and daylight saving than the TZCODE - structure. - - The macro _pcps_has_pcps_tzdl() or the API call mbg_dev_has_pcps_tzdl() - check whether this call is supported by a device. - - Other cards may support the mbg_get_tzcode() or mbg_get_gps_tzdl() - calls instead. - + * + * This function fills up a ::PCPS_TZDL structure which supports a more + * detailed configuration of time zone and daylight saving than the ::TZCODE + * structure. + * + * The API call ::mbg_chk_dev_has_pcps_tzdl checks whether + * this call is supported by a device. + * + * Other devices may support the ::mbg_get_tzcode or ::mbg_get_gps_tzdl + * calls instead. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZDL structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pcps_tzdl + * @param[out] p Pointer to a ::PCPS_TZDL structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_pcps_tzdl * @see ::mbg_set_pcps_tzdl * @see ::mbg_get_tzcode * @see ::mbg_get_gps_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_pcps_tzdl( MBG_DEV_HANDLE dh, PCPS_TZDL *p ) ; /** * @brief Write time zone/daylight saving parameters to a device. - - This function passes a ::PCPS_TZDL structure to a device which supports - a more detailed configuration of time zone and daylight saving than the - TZCODE structure. - - The macro _pcps_has_pcps_tzdl() or the API call mbg_dev_has_pcps_tzdl() - check whether this call is supported by a device. - Other cards may support the mbg_set_tzcode() or mbg_set_gps_tzdl() - calls instead. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TZDL structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pcps_tzdl + * + * This function passes a ::PCPS_TZDL structure to a device which supports + * a more detailed configuration of time zone and daylight saving than the + * ::TZCODE structure. + * + * The API call ::mbg_chk_dev_has_pcps_tzdl checks whether + * this call is supported by a device. + * Other cards may support the ::mbg_set_tzcode or ::mbg_set_gps_tzdl + * calls instead. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PCPS_TZDL structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_pcps_tzdl * @see ::mbg_get_pcps_tzdl * @see ::mbg_set_tzcode * @see ::mbg_set_gps_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_pcps_tzdl( MBG_DEV_HANDLE dh, const PCPS_TZDL *p ) ; /** - * @brief Read the %UTC offset configuration of the reference time from a device. - - This parameter is used to specify the %UTC offset of an incoming - reference time signal if a kind of time signal e.g. an IRIG input - signal) does not provide this information. - - The macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() - check whether this call is supported by a device. - + * @brief Read the %UTC offset configuration of the reference time from a device + * + * This parameter is used to specify the %UTC offset of an incoming + * reference time signal if a kind of time signal e.g. an IRIG input + * signal) does not provide this information. + * + * The API call ::mbg_chk_dev_has_ref_offs checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_REF_OFFS value to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ref_offs + * @param[out] p Pointer to a ::MBG_REF_OFFS value to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ref_offs * @see ::mbg_set_ref_offs - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ref_offs( MBG_DEV_HANDLE dh, MBG_REF_OFFS *p ) ; /** * @brief Write the %UTC offset configuration of the reference time to a device. - - This parameter is used to specify the %UTC offset of an incoming - reference time signal if a kind of time signal e.g. an IRIG input - signal) does not provide this information. - - The macro _pcps_has_ref_offs() or the API call mbg_dev_has_ref_offs() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_REF_OFFS value to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ref_offs + * + * This parameter is used to specify the %UTC offset of an incoming + * reference time signal if a kind of time signal e.g. an IRIG input + * signal) does not provide this information. + * + * The API call ::mbg_chk_dev_has_ref_offs checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::MBG_REF_OFFS value to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ref_offs * @see ::mbg_get_ref_offs - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_ref_offs( MBG_DEV_HANDLE dh, const MBG_REF_OFFS *p ) ; /** - * @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags. - - The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current - settings of those flags. - The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() - check whether this call is supported by a device. - + * @brief Read a ::MBG_OPT_INFO structure containing optional settings, controlled by flags + * + * The ::MBG_OPT_INFO structure contains a mask of supported flags plus the current + * settings of those flags. + * + * The API call ::mbg_chk_dev_has_opt_flags checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_OPT_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_opt_flags + * @param[out] p Pointer to a ::MBG_OPT_INFO structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_opt_flags * @see ::mbg_set_opt_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_opt_info( MBG_DEV_HANDLE dh, MBG_OPT_INFO *p ) ; /** * @brief Write a ::MBG_OPT_SETTINGS structure containing optional device settings. - - The macro _pcps_has_opt_flags() or the API call mbg_dev_has_opt_flags() - check whether this call is supported by a device. - The ::MBG_OPT_INFO structure should be read first to check which of the specified - flag is supported by a device. - + * + * The API call ::mbg_chk_dev_has_opt_flags checks whether + * this call is supported by a device. + * + * ::mbg_get_opt_info should be called first to check which of + * the specified flags is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_OPT_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_opt_flags + * @param[out] p Pointer to a ::MBG_OPT_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_opt_flags * @see ::mbg_get_opt_info - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_opt_settings( MBG_DEV_HANDLE dh, const MBG_OPT_SETTINGS *p ) ; /** @@ -1173,19 +3345,19 @@ extern "C" { * ::mbg_get_all_irig_rx_info should be used instead which also reads some * other associated parameters affecting the behaviour of the IRIG input. * - * The API call ::mbg_dev_is_irig_rx checks whether this call is supported - * by a device. + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] *p An ::IRIG_INFO structure to be filled up + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Address of an ::IRIG_INFO structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_all_irig_rx_info * @see ::mbg_set_irig_rx_settings - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode */ _MBG_API_ATTR int _MBG_API mbg_get_irig_rx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) ; @@ -1197,403 +3369,407 @@ extern "C" { * ::mbg_save_all_irig_rx_settings should be used instead which also writes some * other associated parameters affecting the behaviour of the IRIG input. * - * The API call ::mbg_dev_is_irig_rx checks whether this call is supported - * by a device. The ::IRIG_INFO structure should be read first to determine + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. + * ::mbg_get_irig_rx_info should be called first to determine * the possible settings supported by the device's IRIG input. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[in] p Pointer to a ::IRIG_SETTINGS structure to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::IRIG_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_save_all_irig_rx_settings * @see ::mbg_get_irig_rx_info - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode */ _MBG_API_ATTR int _MBG_API mbg_set_irig_rx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) ; /** - * @brief Read all IRIG input configuration information from a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pdev Pointer to the device's ::PCPS_DEV structure - @param p_irig_info Pointer to a ::IRIG_SETTINGS structure to be written - @param p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written - @param p_opt_info Pointer to a ::MBG_OPT_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Read all IRIG input configuration information from a device + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] pdev Pointer to the device's ::PCPS_DEV structure //### TODO Make this obsolete + * @param[in] p_irig_info Pointer to a ::IRIG_SETTINGS structure to be written + * @param[in] p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written + * @param[in] p_opt_info Pointer to a ::MBG_OPT_SETTINGS structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_save_all_irig_rx_settings * @see ::mbg_set_irig_rx_settings * @see ::mbg_set_ref_offs * @see ::mbg_set_opt_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_all_irig_rx_info( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, IRIG_INFO *p_irig_info, MBG_REF_OFFS *p_ref_offs, MBG_OPT_INFO *p_opt_info ) ; /** * @brief Write all IRIG input configuration settings to a device. - - The macro _pcps_is_irig_rx() or the API call mbg_dev_is_irig_rx() - check whether this call is supported by a device. - The ::IRIG_INFO structure should be read first to determine the possible - settings supported by this card's IRIG input. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pdev Pointer to the device's ::PCPS_DEV structure - @param p_irig_settings Pointer to a ::IRIG_SETTINGS structure to be written - @param p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written - @param p_opt_settings Pointer to a ::MBG_OPT_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The API call ::mbg_chk_dev_is_tcr checks whether + * this call is supported by a device. + * ::mbg_get_all_irig_rx_info should be called before to determine + * the possible settings supported by the IRIG input. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] pdev Pointer to the device's ::PCPS_DEV structure //### TODO Make this obsolete + * @param[out] p_irig_settings Pointer to a ::IRIG_SETTINGS structure to be written + * @param[out] p_ref_offs Pointer to a ::MBG_REF_OFFS structure to be written + * @param[out] p_opt_settings Pointer to a ::MBG_OPT_SETTINGS structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_all_irig_rx_info * @see ::mbg_set_irig_rx_settings * @see ::mbg_set_ref_offs * @see ::mbg_set_opt_settings -*/ - _MBG_API_ATTR int _MBG_API mbg_save_all_irig_rx_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const IRIG_SETTINGS *p_irig_settings, const MBG_REF_OFFS *p_ref_offs, const MBG_OPT_SETTINGS *p_opt_settings ) ; - - /** - * @brief Check if a device supports the ::mbg_get_irig_ctrl_bits call - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - * - * @see ::mbg_get_irig_ctrl_bits */ - _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_ctrl_bits( MBG_DEV_HANDLE dh, int *p ) ; + _MBG_API_ATTR int _MBG_API mbg_save_all_irig_rx_settings( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, const IRIG_SETTINGS *p_irig_settings, const MBG_REF_OFFS *p_ref_offs, const MBG_OPT_SETTINGS *p_opt_settings ) ; /** * @brief Read the control function bits received from an incoming IRIG signal. - - This function fills a ::MBG_IRIG_CTRL_BITS structure with the control function - bits decoded from the incoming IRIG signal. - - The meaning of these bits depends on the type of IRIG code frame format. - - In some IRIG formats these bits provide some well-known information which can - also be evaluated by the device. For example, in IEEE 1344 or IEEE C37.118 code - the control function bits are used to provide the year number, UTC offset, - DST status, leap second warning, etc. - - For most IRIG code formats, however, these bits are reserved, i.e. not used - at all, or application defined, depending on the configuration of the IRIG - generator providing the IRIG signal. - - In the latter case the application has to evaluate the received control function - bits and can use this function to retrieve these bits from the receiver device. - - The macro _pcps_has_irig_ctrl_bits() or the API call mbg_dev_has_irig_ctrl_bits() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_IRIG_CTRL_BITS type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES * - * @see ::mbg_dev_has_irig_ctrl_bits - */ - _MBG_API_ATTR int _MBG_API mbg_get_irig_ctrl_bits( MBG_DEV_HANDLE dh, MBG_IRIG_CTRL_BITS *p ) ; - - /** - * @brief Check if a device supports the mbg_get_raw_irig_data() call. - + * This function fills an ::MBG_IRIG_CTRL_BITS structure with the control function + * bits decoded from the incoming IRIG signal. + * + * The meaning of these bits depends on the type of IRIG code frame format. + * + * In some IRIG formats these bits provide some well-known information which can + * also be evaluated by the device. For example, in IEEE 1344 or IEEE C37.118 code + * the control function bits are used to provide the year number, UTC offset, + * DST status, leap second warning, etc. + * + * For most IRIG code formats, however, these bits are reserved, i.e. not used + * at all, or application defined, depending on the configuration of the IRIG + * generator providing the IRIG signal. + * + * In the latter case the application has to evaluate the received control function + * bits and can use this function to retrieve these bits from the receiver device. + * + * The API call ::mbg_chk_dev_has_irig_ctrl_bits checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::MBG_IRIG_CTRL_BITS type to be filled up. * - * @see ::mbg_get_raw_irig_data - * @see ::mbg_get_raw_irig_data_on_sec_change + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_irig_ctrl_bits */ - _MBG_API_ATTR int _MBG_API mbg_dev_has_raw_irig_data( MBG_DEV_HANDLE dh, int *p ) ; + _MBG_API_ATTR int _MBG_API mbg_get_irig_ctrl_bits( MBG_DEV_HANDLE dh, MBG_IRIG_CTRL_BITS *p ) ; /** * @brief Read raw IRIG data from an IRIG receiver. - - This function fills a ::MBG_RAW_IRIG_DATA structure with the raw data bits received - from the incoming IRIG signal. This enables an application itself to decode the - information provided by the IRIG signal. - - The macro _pcps_has_raw_irig_data() or the API call mbg_dev_has_raw_irig_data() - check whether this call is supported by a device. - + * + * This function reads an ::MBG_RAW_IRIG_DATA structure with the raw data bits received + * from the incoming IRIG signal. This enables an application itself to decode the + * information provided by the IRIG signal. + * + * The API call ::mbg_chk_dev_has_raw_irig_data checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up * - * @see ::mbg_dev_has_raw_irig_data + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_raw_irig_data * @see ::mbg_get_raw_irig_data_on_sec_change */ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) ; /** * @brief Wait for second changeover then read raw IRIG data from an IRIG receiver. - - This function waits until the second of the device's on-board time rolls over, and - then reads the last recent raw IRIG data from the device. - - The macro _pcps_has_raw_irig_data() or the API call mbg_dev_has_raw_irig_data() - check whether this call is supported by a device. - - <b>Note:</b> The mbg_get_time_sec_change() function called by this function is - supported under Windows only, so this function can also only be used under Windows. - + * + * This function waits until the second of the device's on-board time rolls over, + * and then reads the last recent raw IRIG data from the device. + * + * The API call ::mbg_chk_dev_has_raw_irig_data checks whether + * this call is supported by a device. + * + * <b>Note:</b> The ::mbg_get_time_sec_change function called + * by this function is supported under Windows only, so this function + * can also be used under Windows only. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_raw_irig_data + * @param[out] p Pointer to a ::MBG_RAW_IRIG_DATA type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_raw_irig_data * @see ::mbg_get_raw_irig_data * @see ::mbg_get_time_sec_change -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_raw_irig_data_on_sec_change( MBG_DEV_HANDLE dh, MBG_RAW_IRIG_DATA *p ) ; /** - * @brief Check if a device supports the mbg_get_irig_time() call. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_irig_time -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_time( MBG_DEV_HANDLE dh, int *p ) ; - - /** * @brief Read the IRIG time and day-of-year number from an IRIG receiver. - - Fills up a ::PCPS_IRIG_TIME structure with the raw IRIG day-of-year number - and time decoded from the latest IRIG input frame. If the configured IRIG code - also contains the year number then the year number is also returned, otherwise - the returned year number is 0xFF. - - The macro _pcps_has_irig_time() or the API call mbg_dev_has_irig_time() - check whether this call is supported by a device. - + * + * Reads a ::PCPS_IRIG_TIME structure with the raw IRIG day-of-year number + * and time decoded from the latest IRIG input frame. If the configured IRIG code + * also contains the year number then the year number is also returned, otherwise + * the returned year number is 0xFF. + * + * The API call ::mbg_chk_dev_has_irig_time checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_IRIG_TIME type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_irig_time -*/ + * @param[out] p Pointer to a ::PCPS_IRIG_TIME type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_irig_time + */ _MBG_API_ATTR int _MBG_API mbg_get_irig_time( MBG_DEV_HANDLE dh, PCPS_IRIG_TIME *p ) ; /** * @brief Clear a device's on-board time capture FIFO buffer. - - The macro _pcps_can_clr_ucap_buff() or the API call mbg_dev_can_clr_ucap_buff() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_can_clr_ucap_buff checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_can_clr_ucap_buff + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_can_clr_ucap_buff * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event - */ + */ _MBG_API_ATTR int _MBG_API mbg_clr_ucap_buff( MBG_DEV_HANDLE dh ) ; /** * @brief Read information on a device's event capture buffer. - - Fills a ::PCPS_UCAP_ENTRIES structure with the number of user capture - events actually stored in the FIFO buffer, and the maximum number of - events that can be held by the buffer. - - The macro _pcps_has_ucap() or the API call mbg_dev_has_ucap() - check whether this call is supported by a device. - + * + * Reads a ::PCPS_UCAP_ENTRIES structure with the number of user capture + * events actually stored in the FIFO buffer, and the maximum number of + * events that can be held by the buffer. + * + * The API call ::mbg_chk_dev_has_ucap checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_UCAP_ENTRIES structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ucap + * @param[out] p Pointer to a ::PCPS_UCAP_ENTRIES structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ucap * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ucap_entries( MBG_DEV_HANDLE dh, PCPS_UCAP_ENTRIES *p ) ; /** - * @brief Retrieve a single time capture event from the on-board FIFO buffer. - - The capture event is returned in a ::PCPS_HR_TIME structure. The oldest entry - in the FIFO is retrieved and then removed from the FIFO. - - If no capture event is available in the FIFO buffer then both the seconds - and the fractions of the returned timestamp are 0. - - The macro _pcps_has_ucap() or the API call mbg_dev_has_ucap() - check whether this call is supported by a device. - - <b>Note:</b> This call is very much faster than the older mbg_get_gps_ucap() - call which is obsolete but still supported for compatibility with - older cards. - + * @brief Retrieve a single time capture event from the on-board FIFO buffer + * + * The capture event is returned in a ::PCPS_HR_TIME structure. The oldest entry + * in the FIFO is retrieved and then removed from the FIFO. + * + * If no capture event is available in the FIFO buffer then both the seconds + * and the fractions of the returned timestamp are 0. + * + * The API call ::mbg_chk_dev_has_ucap checks whether + * this call is supported by a device. + * + * <b>Note:</b> This call is very much faster than the older ::mbg_get_gps_ucap + * call which is obsolete but still supported for compatibility with + * older cards. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_HR_TIME structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ucap + * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ucap * @see ::mbg_get_ucap_entries * @see ::mbg_clr_ucap_buff - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ucap_event( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p ) ; /** - * @brief Read the card's time zone/daylight saving parameters. - - This function returns the time zone/daylight saving parameters - in a ::TZDL structure. - - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether this call is supported by a device. - - <b>Note:</b> In spite of the function name this call may also be - supported by non-GPS cards. Other cards may support the mbg_get_tzcode() - or mbg_get_pcps_tzdl() calls instead. - + * @brief Read the card's time zone/daylight saving parameters + * + * This function returns the time zone/daylight saving parameters + * in a ::TZDL structure. + * + * The API call ::mbg_chk_dev_has_tzdl checks whether + * this call is supported by a device. + * + * <b>Note:</b> In spite of the function name this call may also be + * supported by non-GPS cards. Other cards may support the ::mbg_get_tzcode + * or ::mbg_get_pcps_tzdl calls instead. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TZDL structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_tzdl + * @param[out] p Pointer to a ::TZDL structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_tzdl * @see ::mbg_set_gps_tzdl * @see ::mbg_get_tzcode * @see ::mbg_get_pcps_tzdl * @see @ref group_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_tzdl( MBG_DEV_HANDLE dh, TZDL *p ) ; /** * @brief Write the card's time zone/daylight saving parameters. - - This function writes the time zone/daylight saving parameters - in a ::TZDL structure to a device. - - The macro _pcps_has_tzdl() or the API call mbg_dev_has_tzdl() - check whether this call is supported by a device. - - <b>Note:</b> In spite of the function name this call may also be - supported by non-GPS cards. Other cards may support the mbg_set_tzcode() - or mbg_set_pcps_tzdl() calls instead. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TZDL structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_tzdl + * + * This function writes the time zone/daylight saving parameters + * in a ::TZDL structure to a device. + * + * The API call ::mbg_chk_dev_has_tzdl checks whether + * this call is supported by a device. + * + * <b>Note:</b> In spite of the function name this call may also be + * supported by non-GPS cards. Other cards may support the ::mbg_set_tzcode + * or ::mbg_set_pcps_tzdl calls instead. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::TZDL structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_tzdl * @see ::mbg_get_gps_tzdl * @see ::mbg_set_tzcode * @see ::mbg_set_pcps_tzdl * @see @ref group_tzdl - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_tzdl( MBG_DEV_HANDLE dh, const TZDL *p ) ; /** - * @brief Retrieve the software revision of a GPS receiver. - - This call is obsolete but still supported for compatibility - with older GPS cards. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> The function mbg_get_gps_receiver_info() should - be used instead, if supported by the card. - + * @brief Retrieve the software revision of a GPS receiver + * + * @deprecated This function is deprecated. + * + * This function is deprecated, but still supported + * for compatibility with older GPS cards. Normally + * the software revision is part of the ::RECEIVER_INFO + * structure. See ::mbg_setup_receiver_info which takes + * care of the different options. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::SW_REV structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_is_gps - * @see ::mbg_get_gps_receiver_info - */ + * @param[out] p Pointer to a ::SW_REV structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_setup_receiver_info + * @see ::mbg_chk_dev_is_gps + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_sw_rev( MBG_DEV_HANDLE dh, SW_REV *p ) ; /** * @brief Retrieve the status of the battery buffered GPS variables. - - These GPS variables hold some parameters sent by the GPS satellites - which are required for proper operation. If the saved set of parameters - is not complete then the GPS receiver stays in COLD BOOT mode until - all data have been received and thus all data sets are valid. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - + * + * GPS receivers require some navigational data set to be available + * to be able to decode position and time accurately. This data set + * is transmitted periodically by the satellites, so it can + * simply be collected if it's not available. + * + * The ::BVAR_STAT type reports which parts of the data set are + * available in the receiver, and which are not. + * + * If the available data set is not complete then the receiver + * stays in COLD BOOT mode until all data have been received + * and thus all data sets are valid. + * + * The API call ::mbg_chk_dev_has_bvar_stat checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::BVAR_STAT structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::BVAR_STAT structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_bvar_stat + * @see ::BVAR_FLAGS */ _MBG_API_ATTR int _MBG_API mbg_get_gps_bvar_stat( MBG_DEV_HANDLE dh, BVAR_STAT *p ) ; /** * @brief Read the current board time using a ::TTM structure. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This API call is pretty slow, so the mbg_get_hr_time_..() - or mbg_get_fast_hr_timestamp...() group of calls should be used preferably. - + * + * The API call ::mbg_chk_dev_has_ttm_time checks whether + * this call is supported by a device. + * + * <b>Note:</b> This API call is very slow, so ::mbg_get_hr_time or + * ::mbg_get_fast_hr_timestamp or associated calls should be used preferably. + * + * <b>Note:</b> This function should be preferred over ::mbg_get_gps_time, + * which has been deprecated. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TTM structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::TTM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ttm_time * @see ::mbg_get_hr_time * @see ::mbg_get_fast_hr_timestamp -*/ - _MBG_API_ATTR int _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p ) ; + */ + _MBG_API_ATTR int _MBG_API mbg_get_ttm_time( MBG_DEV_HANDLE dh, TTM *p ) ; /** - * @brief Set the time on a GPS receiver device. - - Write a ::TTM structure to a GPS receiver in order to set the - on-board date and time. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - + * @brief Read the current board time using a ::TTM structure + * + * The API call ::mbg_chk_dev_has_ttm_time checks whether + * this call is supported by a device. + * + * @deprecated This function is deprecated, use ::mbg_get_ttm_time preferably. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TTM structure to be written + * @param[out] p Pointer to a ::TTM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ttm_time + * @see ::mbg_get_hr_time + * @see ::mbg_get_fast_hr_timestamp + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_get_ttm_time" ) _MBG_API mbg_get_gps_time( MBG_DEV_HANDLE dh, TTM *p ) ; - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + /** + * @brief Set the time on a GPS receiver device + * + * Write a ::TTM structure to a GPS receiver in order to set + * the on-board date and time. Date and time must be local time + * according to the device's on-board time zone configuration + * (::TZDL). + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::TTM structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_set_gps_time( MBG_DEV_HANDLE dh, const TTM *p ) ; /** * @brief Read a ::PORT_PARM structure with a device's serial port configuration. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This function is obsolete since it is only - supported by a certain class of devices and can handle only - up to 2 ports. The generic function mbg_get_serial_settings() - should be used instead. - + * + * @deprecated This function is deprecated, use ::mbg_get_serial_settings preferably. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This function is deprecated since it is only + * supported by a certain class of devices and can handle only + * up to 2 serial ports. The generic function ::mbg_get_serial_settings + * should be used instead. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_PARM structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::PORT_PARM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_serial_settings */ @@ -1601,19 +3777,21 @@ extern "C" { /** * @brief Write a ::PORT_PARM structure to configure the on-board serial ports. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This function is obsolete since it is only - supported by a certain class of devices and can handle only - up to 2 ports. The generic function mbg_save_serial_settings() - should be used instead. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_PARM structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * + * @deprecated This function is deprecated, use ::mbg_save_serial_settings preferably. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This function is deprecated since it is only + * supported by a certain class of devices and can handle only + * up to 2 ports. The generic function ::mbg_save_serial_settings + * should be used instead. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PORT_PARM structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_save_serial_settings */ @@ -1621,177 +3799,181 @@ extern "C" { /** * @brief Read an ::ANT_INFO structure to retrieve an extended GPS antenna status. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> Normally the current antenna connection status can also be - determined by evaluation of the ::PCPS_TIME::signal or ::PCPS_HR_TIME::signal - fields. The "disconnected" status reported by ANT_INFO disappears only if - the antenna has been reconnected <b>and</b> the receiver has synchronized - to the GPS satellites again. - + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> Normally the current antenna connection status can also be + * determined by evaluation of the ::PCPS_TIME::signal or ::PCPS_HR_TIME::signal + * fields. The "disconnected" status reported by ::ANT_INFO disappears only if + * the antenna has been reconnected <b>and</b> the receiver has synchronized + * to the GPS satellites again. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ANT_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::ANT_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_info( MBG_DEV_HANDLE dh, ANT_INFO *p ) ; /** - * @brief Read a time capture event from the on-board FIFO buffer using a ::TTM structure. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - <b>Note:</b> This call is pretty slow and has been obsoleted by - mbg_get_ucap_event() which should be used preferably, if supported - by the device. Anyway, this call is still supported for compatibility - with older devices. - + * @brief Read a time capture event from the on-board FIFO buffer using a ::TTM structure + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * <b>Note:</b> This call is pretty slow and has been obsoleted by + * ::mbg_get_ucap_event which should be used preferably, if supported + * by the device. Anyway, this call is still supported for compatibility + * with older devices which don't support ::mbg_get_ucap_event. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TTM structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::TTM structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_ucap_entries * @see ::mbg_get_ucap_event * @see ::mbg_clr_ucap_buff -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ucap( MBG_DEV_HANDLE dh, TTM *p ) ; /** - * @brief Read the ::ENABLE_FLAGS structure controlling when outputs are to be enabled. - - The ::ENABLE_FLAGS structure controls whether certain outputs - shall be enabled immediately after the card's power-up, or only - after the card has synchronized to its input signal. - - The macro _pcps_has_gps_data() or the API call mbg_dev_has_gps_data() - check whether this call is supported by a device. - - <b>Note:</b> Not all of the input signals specified for the - ::ENABLE_FLAGS structure can be modified individually. - + * @brief Read the ::ENABLE_FLAGS structure controlling when outputs are to be enabled + * + * The ::ENABLE_FLAGS structure controls whether certain signal outputs + * are to be enabled immediately after the device's power-up, or only + * after the device has synchronized to its input signal. + * + * The function ::mbg_chk_dev_has_gps_data can be used to check + * whether this call is supported by a device. + * + * <b>Note:</b> Not all of the input signals specified for the + * ::ENABLE_FLAGS structure can be modified individually. + * See ::ENABLE_FLAGS_CODES. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::ENABLE_FLAGS structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::ENABLE_FLAGS structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::ENABLE_FLAGS + * @see ::ENABLE_FLAGS_CODES * @see ::mbg_set_gps_enable_flags -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_enable_flags( MBG_DEV_HANDLE dh, ENABLE_FLAGS *p ) ; /** - * @brief Write an ENABLE_FLAGS structure to configure when outputs shall be enabled. - - The ::ENABLE_FLAGS structure controls whether certain outputs - shall be enabled immediately after the card's power-up, or only - after the card has synchronized to its input signal. - - The macro _pcps_has_gps_data() or the API call mbg_dev_has_gps_data() - check whether this call is supported by a device. - - <b>Note:</b> Not all of the input signals specified for the - ENABLE_FLAGS structure can be modified individually. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ENABLE_FLAGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Write an ;;ENABLE_FLAGS structure to configure when outputs shall be enabled. + * + * The ::ENABLE_FLAGS structure controls whether certain signal outputs + * are to be enabled immediately after the device's power-up, or only + * after the device has synchronized to its input signal. + * + * The function ::mbg_chk_dev_has_gps_data can be used to check + * whether this call is supported by a device. + * + * <b>Note:</b> Not all of the input signals specified for the + * ::ENABLE_FLAGS structure can be modified individually. + * See ::ENABLE_FLAGS_CODES. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ENABLE_FLAGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::ENABLE_FLAGS + * @see ::ENABLE_FLAGS_CODES * @see ::mbg_get_gps_enable_flags -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_enable_flags( MBG_DEV_HANDLE dh, const ENABLE_FLAGS *p ) ; /** * @brief Read the extended GPS receiver status from a device. - - The ::STAT_INFO structure reports the status of the GPS receiver, - including mode of operation and number of visible/usable satellites. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - + * + * The ::STAT_INFO structure reports the status of the GPS receiver, + * including mode of operation and number of visible/usable satellites. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::STAT_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::STAT_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::STAT_INFO -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_stat_info( MBG_DEV_HANDLE dh, STAT_INFO *p ) ; /** - * @brief Send a ::GPS_CMD to a GPS receiver device. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::GPS_CMD - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::PC_GPS_CMD_BOOT, ::PC_GPS_CMD_INIT_SYS, ::PC_GPS_CMD_INIT_USER, ::PC_GPS_CMD_INIT_DAC -*/ + * @brief Send one of the ::PC_GPS_COMMANDS to a GPS receiver device + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::GPS_CMD + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::PC_GPS_COMMANDS + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_cmd( MBG_DEV_HANDLE dh, const GPS_CMD *p ) ; /** - * @brief Read the current geographic position from a GPS device. - - The returned ::POS structure contains the current position in - ECEF (Earth Centered, Earth Fixed) kartesian coordinates, and in - geographic coordinates with different formats, using the WGS84 - geographic datum. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - + * @brief Read the current geographic position from a GPS/GNSS device. + * + * The returned ::POS structure contains the current position in + * ECEF (Earth Centered, Earth Fixed) kartesian coordinates, and in + * geographic coordinates with different formats, using the WGS84 + * geographic datum. + * + * The API call ::mbg_chk_dev_has_rcvr_pos checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::POS structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::POS structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_gps_pos_xyz * @see ::mbg_set_gps_pos_lla -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_pos( MBG_DEV_HANDLE dh, POS *p ) ; /** - * @brief Set the GPS receiver position using ::XYZ coordinates. - - The structure ::XYZ must specify the new position in ECEF - (Earth Centered, Earth Fixed) kartesian coordinates. - - The macro _pcps_is_gps() or the API call mbg_dev_is_gps() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param p Position in ::XYZ format to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Set the GPS/GNSS receiver position using ::XYZ coordinates. + * + * The structure ::XYZ must specify the new position in ECEF + * (Earth Centered, Earth Fixed) kartesian coordinates. + * + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Position in ::XYZ format to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_gps_pos_lla * @see ::mbg_get_gps_pos -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_xyz( MBG_DEV_HANDLE dh, const XYZ p ) ; /** - * @brief Set the GPS receiver position using ::LLA coordinates + * @brief Set the GPS/GNSS receiver position using ::LLA coordinates. * * The structure ::LLA must specify the new position as longitude, * latitude, and altitude, using the WGS84 geographic datum. * - * The macro ::_pcps_is_gps or the API call ::mbg_dev_is_gps - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_is_gps checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param p Position in ::LLA format to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Position in ::LLA format to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_set_gps_pos_xyz * @see ::mbg_get_gps_pos @@ -1799,21 +3981,21 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_set_gps_pos_lla( MBG_DEV_HANDLE dh, const LLA p ) ; /** - * @brief Read the configured GPS antenna cable length from a device. + * @brief Read the configured antenna cable length from a device * * The antenna cable length parameter is used by GPS/GNSS receivers * to compensate the propagation delay of the RF signal over the antenna * cable, which is about 5 ns/m. * - * The macro ::_pcps_has_cab_len or the API call ::mbg_dev_has_cab_len - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_cab_len checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p ::ANT_CABLE_LEN structure to be filled up + * @param[out] p Pointer to an ::ANT_CABLE_LEN structure to be filled up. * - * @return One of the @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_cab_len + * @see ::mbg_chk_dev_has_cab_len * @see ::mbg_set_gps_ant_cable_len */ _MBG_API_ATTR int _MBG_API mbg_get_gps_ant_cable_len( MBG_DEV_HANDLE dh, ANT_CABLE_LEN *p ) ; @@ -1825,460 +4007,442 @@ extern "C" { * to compensate the propagation delay of the RF signal over the antenna * cable, which is about 5 ns/m. * - * The macro ::_pcps_has_cab_len or the API call ::mbg_dev_has_cab_len - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_cab_len checks whether + * this call is supported by a device. * * @note Different devices may accept different maximum values, so the * written value should be re-read using ::mbg_get_gps_ant_cable_len * to check if the parameter has been accepted. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p ::ANT_CABLE_LEN structure to be written + * @param[out] p Pointer to an ::ANT_CABLE_LEN structure to be written. * - * @return One of the @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_cab_len + * @see ::mbg_chk_dev_has_cab_len * @see ::mbg_get_gps_ant_cable_len -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_ant_cable_len( MBG_DEV_HANDLE dh, const ANT_CABLE_LEN *p ) ; /** - * @brief Read the ::RECEIVER_INFO structure from a device. - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check whether this call is supported by a device. - - <b>Note:</b> Applications should call mbg_setup_receiver_info() - preferably, which also sets up a basic ::RECEIVER_INFO structure - for devices which don't provide that structure by themselves. - + * @brief Read the ::RECEIVER_INFO structure from a device + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * whether this call is supported by a device. + * + * <b>Note:</b> Applications should call ::mbg_setup_receiver_info + * preferably, which also sets up a basic ::RECEIVER_INFO structure + * for devices which don't provide that structure by themselves. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::RECEIVER_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::RECEIVER_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_setup_receiver_info -*/ + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_receiver_info( MBG_DEV_HANDLE dh, RECEIVER_INFO *p ) ; /** * @brief Read a ::STR_TYPE_INFO_IDX array of supported string types. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - - <b>Note:</b> The function mbg_get_serial_settings() should be used preferably - to get retrieve the current port settings and configuration options. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param stii Pointer to a an array of string type information to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_setup_receiver_info - * @see ::mbg_get_gps_all_port_info + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * <b>Note:</b> The function ::mbg_get_serial_settings should be used preferably + * to get retrieve the current port settings and configuration options. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] stii Pointer to a an array of string type information to be filled up. + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_serial_settings -*/ + * @see ::mbg_get_gps_all_port_info + * @see ::mbg_setup_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_str_type_info( MBG_DEV_HANDLE dh, STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) ; /** * @brief Read a ::PORT_INFO_IDX array of supported serial port configurations. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - - <b>Note:</b> The function mbg_get_serial_settings() should be used preferably - to get retrieve the current port settings and configuration options. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pii Pointer to a an array of port configuration information to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_setup_receiver_info - * @see ::mbg_get_gps_all_str_type_info + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * <b>Note:</b> The function ::mbg_get_serial_settings should be used preferably + * to get retrieve the current port settings and configuration options. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] pii Pointer to a an array of port configuration information to be filled up. + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_serial_settings -*/ + * @see ::mbg_get_gps_all_str_type_info + * @see ::mbg_setup_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_port_info( MBG_DEV_HANDLE dh, PORT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) ; /** * @brief Write the configuration for a single serial port to a device. - - The ::PORT_SETTINGS_IDX structure contains both the ::PORT_SETTINGS - and the port index value. Except for the parameter types this call is - equivalent to mbg_set_gps_port_settings(). - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check whether this call is supported by a device. - - <b>Note:</b> The function mbg_save_serial_settings() should be used preferably - to write new port configuration to the board. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_SETTINGS_IDX structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::PORT_SETTINGS_IDX structure contains both the ::PORT_SETTINGS + * and the port index value. Except for the parameter types this call is + * equivalent to ::mbg_set_gps_port_settings. + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * whether this call is supported by a device. + * + * <b>Note:</b> The function ::mbg_save_serial_settings should be used preferably + * to write new port configuration to the board. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PORT_SETTINGS_IDX structure to be written + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_save_serial_settings * @see ::mbg_set_gps_port_settings - * @see ::mbg_dev_has_receiver_info -*/ + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings_idx( MBG_DEV_HANDLE dh, const PORT_SETTINGS_IDX *p ) ; /** * @brief Write the configuration for a single serial port to a device. - - The ::PORT_SETTINGS structure does not contain the port index, so the - the port index must be given separately. Except for the parameter types - this call is equivalent to mbg_set_gps_port_settings_idx(). - - The macro _pcps_has_receiver_info() or the API call mbg_dev_has_receiver_info() - check whether this call is supported by a device. - - <b>Note:</b> The function mbg_save_serial_settings() should be used preferably - to write new port configuration to the board. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PORT_SETTINGS structure to be filled up - @param idx Index of the serial port to be configured (starting from 0 ). - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::PORT_SETTINGS structure does not contain the port index, so the + * the port index must be given separately. Except for the parameter types + * this call is equivalent to ::mbg_set_gps_port_settings_idx. + * + * The API call ::mbg_chk_dev_has_receiver_info checks + * whether this call is supported by a device. + * + * <b>Note:</b> The function ::mbg_save_serial_settings should be used preferably + * to write new port configuration to the board. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::PORT_SETTINGS structure to be written. + * @param[in] idx Index of the serial port to be configured (starting from 0). + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_save_serial_settings * @see ::mbg_set_gps_port_settings_idx - * @see ::mbg_dev_has_receiver_info -*/ + * @see ::mbg_chk_dev_has_receiver_info + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_port_settings( MBG_DEV_HANDLE dh, const PORT_SETTINGS *p, int idx ) ; /** * @brief Set up a ::RECEIVER_INFO structure for a device. - - If the device supports the ::RECEIVER_INFO structure then the structure - is read from the device, otherwise a structure is set up using - default values depending on the device type. - The function mbg_get_device_info() must have been called before, - and the returned PCPS_DEV structure passed to this function. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *pdev Pointer to a ::PCPS_DEV structure returned by mbg_get_device_info() - @param *p Pointer to a ::RECEIVER_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * If the device supports the ::RECEIVER_INFO structure then the structure + * is read from the device, otherwise a structure is set up using + * default values depending on the device type. + * + * Optionally, the function ::mbg_get_device_info may have been called + * before, and the returned ::PCPS_DEV structure can be passed to this + * function. + * + * If a NULL pointer is passed instead, the device info is retrieved + * directly from the device, using the device handle. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p_obs Obsolete pointer kept for compatibility, should be NULL. + * @param[out] p Pointer to a ::RECEIVER_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_device_info - * @see ::mbg_dev_has_receiver_info -*/ - _MBG_API_ATTR int _MBG_API mbg_setup_receiver_info( MBG_DEV_HANDLE dh, const PCPS_DEV *pdev, RECEIVER_INFO *p ) ; + * @see ::mbg_chk_dev_has_receiver_info + */ + _MBG_API_ATTR int _MBG_API mbg_setup_receiver_info( MBG_DEV_HANDLE dh, const void *p_obs, RECEIVER_INFO *p ) ; /** * @brief Read the version code of the on-board PCI/PCIe interface ASIC. - - The macro _pcps_has_asic_version() or the API call mbg_dev_has_asic_version() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_has_asic_version checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCI_ASIC_VERSION type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_asic_version -*/ + * @param[out] p Pointer to a ::PCI_ASIC_VERSION type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_asic_version + */ _MBG_API_ATTR int _MBG_API mbg_get_asic_version( MBG_DEV_HANDLE dh, PCI_ASIC_VERSION *p ) ; /** - * @brief Read the features of the on-board PCI/PCIe interface ASIC. - - The macro _pcps_has_asic_features() or the API call mbg_dev_has_asic_features() - check whether this call is supported by a device. - + * @brief Read the features of the on-board PCI/PCIe interface ASIC + * + * The API call ::mbg_chk_dev_has_asic_features checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCI_ASIC_FEATURES type to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_asic_features -*/ + * @param[out] p Pointer to a ::PCI_ASIC_FEATURES type to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_asic_features + */ _MBG_API_ATTR int _MBG_API mbg_get_asic_features( MBG_DEV_HANDLE dh, PCI_ASIC_FEATURES *p ) ; /** - * @brief Check if a device supports configurable time scales. - - By default the cards return UTC and/or local time. However, some cards - can be configured to return raw GPS time or TAI instead. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_time_scale_info - * @see ::mbg_set_time_scale_settings -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_time_scale( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Read the current time scale settings and which time scales are supported. - - The ::MBG_TIME_SCALE_INFO structure tells which time scale settings are supported - by a device, and which time scale is currently configured. - - The macro _pcps_has_time_scale() or the API call mbg_dev_has_time_scale() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_time_scale(). - + * @brief Read the current time scale settings and which time scales are supported + * + * The ::MBG_TIME_SCALE_INFO structure tells which time scale settings are supported + * by a device, and which time scale is currently configured. + * + * The API call ::mbg_chk_dev_has_time_scale checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_time_scale. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_TIME_SCALE_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::MBG_TIME_SCALE_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_time_scale_settings - * @see ::mbg_dev_has_time_scale -*/ + * @see ::mbg_chk_dev_has_time_scale + */ _MBG_API_ATTR int _MBG_API mbg_get_time_scale_info( MBG_DEV_HANDLE dh, MBG_TIME_SCALE_INFO *p ) ; /** - * @brief Write the time scale configuration to a device. - - The ::MBG_TIME_SCALE_SETTINGS structure determines which time scale - is to be used for the time stamps which can be read from a device. - - The macro _pcps_has_time_scale() or the API call mbg_dev_has_time_scale() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_time_scale(). - - The function mbg_get_time_scale_info() should have been called before - in order to determine which time scales are supported by the card. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_TIME_SCALE_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Write the time scale configuration to a device + * + * The ::MBG_TIME_SCALE_SETTINGS structure determines which time scale + * is to be used for the time stamps which can be read from a device. + * + * The API call ::mbg_chk_dev_has_time_scale checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_time_scale. + * + * The function ::mbg_get_time_scale_info should have been called before + * in order to determine which time scales are supported by the card. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::MBG_TIME_SCALE_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_time_scale_info - * @see ::mbg_dev_has_time_scale -*/ + * @see ::mbg_chk_dev_has_time_scale + */ _MBG_API_ATTR int _MBG_API mbg_set_time_scale_settings( MBG_DEV_HANDLE dh, const MBG_TIME_SCALE_SETTINGS *p ) ; /** - * @brief Check if a device support reading/writing of UTC parameters. - - This API call checks if a device supports reading/writing a GPS UTC - parameter set via the PC bus. Reading/writing these parameters via the - serial port using the Meinberg binary data protocol is supported by all - Meinberg GPS devices. - - The UTC parameter set is usually received from the satellites' broadcasts - and contains the current time offset between GPS time and UTC, plus information - on a pending leap second event. - - It may be useful to overwrite them to do some tests, or for applications - where a card is freewheeling. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_utc_parm - * @see ::mbg_set_utc_parm -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_utc_parm( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Read a ::UTC parameter structure from a device. - - The macro _pcps_has_utc_parm() or the API call mbg_dev_has_utc_parm() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_utc_parm(). - + * @brief Read a ::UTC parameter structure from a device + * + * The API call ::mbg_chk_dev_has_utc_parm checks whether + * this call is supported by a device. + * + * See also the notes for ::mbg_chk_dev_has_utc_parm. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::UTC structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_utc_parm + * @param[out] p Pointer to a ::UTC structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_utc_parm * @see ::mbg_set_utc_parm -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_utc_parm( MBG_DEV_HANDLE dh, UTC *p ) ; /** * @brief Write a ::UTC parameter structure to a device. - - This should only be done for testing, or if a card is operated in - freewheeling mode. If the receiver is tracking any satellites then the settings - written to the device are overwritten by the parameters broadcasted - by the satellites. - - The macro _pcps_has_utc_parm() or the API call mbg_dev_has_utc_parm() - check whether this call is supported by a device. - See also the notes for mbg_dev_has_utc_parm(). - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a valid ::UTC structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_utc_parm + * + * This should only be done for testing, or if a card is operated in + * freewheeling mode. If the receiver is tracking any satellites then the settings + * written to the device are overwritten by the parameters broadcast + * by the satellites. + * + * The API call ::mbg_chk_dev_has_utc_parm checks whether + * this call is supported by a device. + * + * See also the notes for mbg_chk_dev_has_utc_parm. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a valid ::UTC structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_utc_parm * @see ::mbg_get_utc_parm -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_utc_parm( MBG_DEV_HANDLE dh, const UTC *p ) ; /** * @brief Read the current time plus the associated PC cycles from a device. - - The ::PCPS_TIME_CYCLES structure contains a ::PCPS_TIME structure - and a PC cycle counter value which can be used to compensate the latency - of the call, i.e. the program execution time until the time stamp has actually - been read from the board. - - This call is supported for any card, similar to mbg_get_time(). However, - the mbg_get_hr_time_cyles() call should be used preferably if supported by - the device since that call provides much better accuracy than this one. - - The cycle counter value corresponds to a value returned by QueryPerformanceCounter() - under Windows, and get_cycles() under Linux. On operating systems or targets which don't - provide a cycles counter the returned cycles value is always 0. - - Applications should first pick up their own cycle counter value and then call - this function. The difference of the cycle counter values corresponds to the - latency of the call in units of the cycle counter clock frequency, e.g as reported - by QueryPerformanceFrequency() under Windows. - + * + * The ::PCPS_TIME_CYCLES structure contains a ::PCPS_TIME structure + * and a PC cycles counter value which can be used to compensate the latency + * of the call, i.e. the program execution time until the time stamp has actually + * been read from the board. + * + * This call is supported for any card, similar to ::mbg_get_time. However, + * the ::mbg_get_hr_time_cycles call should be used preferably if supported by + * the device since that call provides much better accuracy than this one. + * + * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() + * under Windows, and get_cycles() under Linux. On operating systems or targets which don't + * provide a cycles counter the returned cycles value is always 0. + * + * Applications should first pick up their own cycles counter value and then call + * this function. The difference of the cycles counter values corresponds to the + * latency of the call in units of the cycles counter clock frequency, e.g as reported + * by QueryPerformanceFrequency() under Windows. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_CYCLES structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to a ::PCPS_TIME_CYCLES structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_legacy_time_fncs * @see ::mbg_get_hr_time_cycles * @see ::mbg_get_hr_time_comp * @see ::mbg_get_hr_time * @see ::mbg_get_time -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_time_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_CYCLES *p ) ; /** * @brief Read the current high resolution time plus the associated PC cycles from a device. - - The ::PCPS_HR_TIME_CYCLES structure contains a ::PCPS_HR_TIME structure - and a PC cycle counter value which can be used to compensate the latency - of the call, i.e. the program execution time until the time stamp has actually - been read from the board. - - The macro _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() - check whether this call is supported by a device. - - The cycle counter value corresponds to a value returned by QueryPerformanceCounter() - under Windows, and get_cycles() under Linux. On operating systems or targets which don't - provide a cycles counter the returned cycles value is always 0. - - Applications should first pick up their own cycle counter value and then call - this function. The difference of the cycle counter values corresponds to the - latency of the call in units of the cycle counter clock frequency, e.g as reported - by QueryPerformanceFrequency() under Windows. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_HR_TIME_CYCLES structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_hr_time_comp + * + * The returned ::PCPS_HR_TIME_CYCLES structure contains a ::PCPS_HR_TIME + * structure and a PC cycles counter value which can be used to compensate + * the latency of the call, i.e. the program execution time until the time stamp + * has actually been read from the board. + * + * The API call ::mbg_chk_dev_has_hr_time checks whether + * this call is supported by the device. + * + * For details see @ref ::mbgdevio_hr_time_fncs + * + * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() + * under Windows, and get_cycles() under Linux. On operating systems or targets which don't + * provide a cycles counter the returned cycles value is always 0. + * + * Applications should first pick up their own cycles counter value and then call + * this function. The difference of the cycles counter values corresponds to the + * latency of the call in units of the cycles counter clock frequency, e.g as reported + * by QueryPerformanceFrequency() under Windows. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_HR_TIME_CYCLES structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_hr_time_fncs + * @see ::mbg_chk_dev_has_hr_time * @see ::mbg_get_hr_time - * @see ::mbg_get_time_cycles - * @see ::mbg_get_time -*/ + * @see ::mbg_get_hr_time_cycles + * @see ::mbg_get_hr_time_comp + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_cycles( MBG_DEV_HANDLE dh, PCPS_HR_TIME_CYCLES *p ) ; /** * @brief Read the current high resolution time, and compensate the call's latency. - - Read a ::PCPS_HR_TIME structure plus cycle counter value, and correct the - time stamp for the latency of the call as described for mbg_get_hr_time_cycles(), - then return the compensated time stamp and optionally the latency. - - The macro _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() - check whether this call is supported by a device. - - The cycle counter value corresponds to a value returned by QueryPerformanceCounter() - under Windows, and get_cycles() under Linux. On operating systems or targets which don't - provide a cycles counter the returned cycles value is always 0. - - Applications should first pick up their own cycle counter value and then call - this function. The difference of the cycle counter values corresponds to the - latency of the call in units of the cycle counter clock frequency, e.g as reported - by QueryPerformanceFrequency() under Windows. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_HR_TIME structure to be filled up - @param *hns_latency Optional pointer to an int32_t value to return - the latency in 100ns units. Pass NULL if not used. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_hr_time_comp + * + * Read a ::PCPS_HR_TIME structure plus cycles counter value, and correct the + * time stamp for the latency of the call as described for ::mbg_get_hr_time_cycles, + * then return the compensated time stamp, and optionally the latency. + * + * The API call ::mbg_chk_dev_has_hr_time checks whether + * this call is supported by the device. + * + * For details see @ref ::mbgdevio_hr_time_fncs + * + * The cycles counter value corresponds to a value returned by QueryPerformanceCounter() + * under Windows, and get_cycles() under Linux. On operating systems or targets which don't + * provide a cycles counter the returned cycles value is always 0. + * + * Applications should first pick up their own cycles counter value and then call + * this function. The difference of the cycles counter values corresponds to the + * latency of the call in units of the cycles counter clock frequency, e.g as reported + * by QueryPerformanceFrequency() under Windows. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_HR_TIME structure to be filled up + * @param[out] hns_latency Optional pointer to an int32_t value to return + * the latency in 100ns units, or NULL, if not used. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_hr_time_fncs + * @see ::mbg_chk_dev_has_hr_time * @see ::mbg_get_hr_time - * @see ::mbg_get_time_cycles - * @see ::mbg_get_time -*/ + * @see ::mbg_get_hr_time_cycles + * @see ::mbg_get_hr_time_comp + * @see @ref mbgdevio_hr_time_fncs + * @see @ref mbgdevio_fast_timestamp_fncs + * @see @ref mbgdevio_legacy_time_fncs + */ _MBG_API_ATTR int _MBG_API mbg_get_hr_time_comp( MBG_DEV_HANDLE dh, PCPS_HR_TIME *p, int32_t *hns_latency ) ; /** * @brief Read the current IRIG output settings plus the supported settings. - - The returned ::IRIG_INFO structure contains the configuration of an IRIG output - plus the possible settings supported by that output. - - The macro _pcps_has_irig_tx() or the API call mbg_dev_has_irig_tx() - check whether this call is supported by a device. - + * + * The returned ::IRIG_INFO structure contains the configuration of an IRIG output + * plus the possible settings supported by that output. + * + * The API call ::mbg_chk_dev_has_irig_tx checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an ::IRIG_INFO structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @param[out] p Pointer to an ::IRIG_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_irig_tx_settings - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_irig_tx_info( MBG_DEV_HANDLE dh, IRIG_INFO *p ) ; /** - * @brief Write an ::IRIG_SETTINGS structure to a device to configure the IRIG output. - - The macro _pcps_has_irig_tx() or the API call mbg_dev_has_irig_tx() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an ::IRIG_INFO structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Write an ::IRIG_SETTINGS structure to a device to configure the IRIG output + * + * The API call ::mbg_chk_dev_has_irig_tx checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to an ::IRIG_INFO structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_irig_tx_info - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig + * @see ::mbg_chk_dev_has_irig_tx + * @see ::mbg_chk_dev_is_tcr + * @see ::mbg_chk_dev_has_irig * @see @ref group_icode -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_irig_tx_settings( MBG_DEV_HANDLE dh, const IRIG_SETTINGS *p ) ; /** - * @brief Read the current frequency synthesizer settings from a device. + * @brief Read the current frequency synthesizer settings from a device * * Read a ::SYNTH structure containing the configuration of an optional * on-board programmable frequency synthesizer. * - * The macro ::_pcps_has_synth or the API call ::mbg_dev_has_synth - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_synth checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::SYNTH structure to be filled up + * @param[out] p Pointer to a ::SYNTH structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_synth + * @see ::mbg_chk_dev_has_synth * @see ::mbg_set_synth * @see ::mbg_get_synth_state * @see @ref group_synth @@ -2286,1066 +4450,553 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_synth( MBG_DEV_HANDLE dh, SYNTH *p ) ; /** - * @brief Write some frequency synthesizer settings to a device. + * @brief Write frequency synthesizer configuration settings to a device * * Write a ::SYNTH structure containing the configuration of an optional * on-board programmable frequency synthesizer. * - * The macro _pcps_has_synth() or the API call mbg_dev_has_synth() - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_synth checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::SYNTH structure to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::SYNTH structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_synth + * @see ::mbg_chk_dev_has_synth * @see ::mbg_get_synth * @see ::mbg_get_synth_state - * @see @::\ref group_synth + * @see @ref group_synth */ _MBG_API_ATTR int _MBG_API mbg_set_synth( MBG_DEV_HANDLE dh, const SYNTH *p ) ; /** - * @brief Read the current status of the on-board frequency synthesizer. - - The macro _pcps_has_synth() or the API call mbg_dev_has_synth() - check whether this call is supported by a device. - + * @brief Read the current status of the on-board frequency synthesizer + * + * The API call ::mbg_chk_dev_has_synth checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::SYNTH_STATE structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_synth + * @param[out] p Pointer to a ::SYNTH_STATE structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_synth * @see ::mbg_get_synth * @see ::mbg_set_synth * @see @ref group_synth -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_synth_state( MBG_DEV_HANDLE dh, SYNTH_STATE *p ) ; /** - * @brief Check if a device supports the mbg_get_fast_hr_timestamp_...() calls. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_fast_hr_timestamp_cycles - * @see ::mbg_get_fast_hr_timestamp_comp - * @see ::mbg_get_fast_hr_timestamp -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_fast_hr_timestamp( MBG_DEV_HANDLE dh, int *p ) ; - - /** * @brief Read a high resolution ::PCPS_TIME_STAMP_CYCLES structure via memory mapped access. - + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_fast_hr_timestamp + * @param[out] p Pointer to a ::PCPS_TIME_STAMP_CYCLES structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_fast_hr_timestamp_comp * @see ::mbg_get_fast_hr_timestamp -*/ + * @see @ref mbgdevio_fast_timestamp_fncs + */ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_cycles( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP_CYCLES *p ) ; /** - * @brief Read a high resolution timestamp and compensate the latency of the call. - - The retrieved ::PCPS_TIME_STAMP is read from memory mapped registers, - and timestamp is compensated for the call's latency before it is returned. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be filled up - @param *hns_latency Optionally receive the latency in hectonanoseconds - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_fast_hr_timestamp + * @brief Read a high resolution timestamp and compensate the latency of the call + * + * The retrieved ::PCPS_TIME_STAMP is read from memory mapped registers, + * and timestamp is compensated for the call's latency before it is returned. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::PCPS_TIME_STAMP structure to be filled up + * @param[out] hns_latency Optionally receives the latency in hectonanoseconds //### TODO Check if hns + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_fast_hr_timestamp_cycles * @see ::mbg_get_fast_hr_timestamp -*/ + * @see @ref mbgdevio_fast_timestamp_fncs + */ _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp_comp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p, int32_t *hns_latency ) ; /** - * @brief Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access. - - This function does not return or evaluate a cycles count, so the latency - of the call can not be determined. However, depending on the timer hardware - used as cycles counter it may take quite some time to read the cycles count - on some hardware architectures, so this call can be used to yield lower - latencies, under the restriction to be unable to determine the exact latency. - + * @brief Read a high resolution ::PCPS_TIME_STAMP structure via memory mapped access + * + * This function does not return or evaluate a cycles count, so the latency + * of the call can not be determined. However, depending on the timer hardware + * used as cycles counter it may take quite some time to read the cycles count + * on some hardware architectures, so this call can be used to yield lower + * latencies, under the restriction to be unable to determine the exact latency. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_TIME_STAMP structure to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_fast_hr_timestamp + * @param[out] p Pointer to a ::PCPS_TIME_STAMP structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @ingroup mbgdevio_fast_timestamp_fncs + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_fast_hr_timestamp_comp * @see ::mbg_get_fast_hr_timestamp_cycles -*/ - _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p ) ; - - /** - * @brief Check if a device is a GPS receiver. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - */ - _MBG_API_ATTR int _MBG_API mbg_dev_is_gps( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device is a DCF77 receiver. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - */ - _MBG_API_ATTR int _MBG_API mbg_dev_is_dcf( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device is a MSF receiver. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - */ - _MBG_API_ATTR int _MBG_API mbg_dev_is_msf( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device is a WWVB receiver. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - */ - _MBG_API_ATTR int _MBG_API mbg_dev_is_wwvb( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device is any long wave signal receiver. - - Long wave receivers include e.g. DCF77, MSF, WWVB, or JJY. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - */ - _MBG_API_ATTR int _MBG_API mbg_dev_is_lwr( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device provides a configurable IRIG input. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_irig_rx_info - * @see ::mbg_set_irig_rx_settings - * @see ::mbg_dev_has_irig_tx - * @see ::mbg_dev_has_irig -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_is_irig_rx( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports the HR_TIME functions. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_hr_time - * @see ::mbg_get_hr_time_cycles - * @see ::mbg_get_hr_time_comp -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_hr_time( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports configuration of antenna cable length. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_gps_ant_cable_len - * @see ::mbg_set_gps_ant_cable_len -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_cab_len( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports timezone configuration using the ::TZDL structure. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_gps_tzdl - * @see ::mbg_set_gps_tzdl - * @see ::mbg_dev_has_tz -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_tzdl( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports timezone configuration using the ::PCPS_TZDL structure. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_pcps_tzdl - * @see ::mbg_set_pcps_tzdl - * @see ::mbg_dev_has_tz -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_pcps_tzdl( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports timezone configuration using the ::PCPS_TZCODE type. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_tzcode - * @see ::mbg_set_tzcode - * @see ::mbg_dev_has_tz -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_tzcode( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports any kind of timezone configuration. - - This can be used e.g. to check if a specifig dialog or menu has to - be displayed. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_tzdl - * @see ::mbg_dev_has_pcps_tzdl - * @see ::mbg_dev_has_tzcode -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_tz( MBG_DEV_HANDLE dh, int *p ) ; - - /* (Intentionally excluded from Doxygen) - Check if a device supports setting an event time, i.e. - configure a %UTC time when the clock shall generate an event. - - <b>Note:</b> This is only supported by some special firmware. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_set_event_time -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_event_time( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports the ::RECEIVER_INFO structure and related calls. - - @note Older GPS devices may not support that structure. - - The mbg_get_gps_receiver_info() call uses this call to decide whether a - ::RECEIVER_INFO can be read directly from a device, or whether a default - structure has to be set up using default values depending on the device type. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_gps_receiver_info -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_receiver_info( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports the mbg_clr_ucap_buff() call. - - The mbg_clr_ucap_buff() call can be used to clear a card's on-board - time capture FIFO buffer. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_clr_ucap_buff -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_can_clr_ucap_buff( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports the mbg_get_ucap_entries() and mbg_get_ucap_event() calls. - - If the card does not but it is a GPS card then the card provides - a time capture FIFO buffer and the obsolete mbg_get_gps_ucap() - call can be used to retrieve entries from the FIFO buffer. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_ucap_entries - * @see ::mbg_get_ucap_event - * @see ::mbg_clr_ucap_buff - * @see ::mbg_get_gps_ucap -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_ucap( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device provides a configurable IRIG output. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_irig_tx_info - * @see ::mbg_set_irig_tx_settings - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig - * @see @ref group_icode - -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_irig_tx( MBG_DEV_HANDLE dh, int *p ) ; - - /* (Intentionally excluded from Doxygen) - Check if a device provides a serial output supporting - higher baud rates than older cards, i.e. ::DEFAULT_BAUD_RATES_DCF_HS - rather than ::DEFAULT_BAUD_RATES_DCF. - - The mbg_get_serial_settings() takes care of this, so applications - which use that call as suggested won't need to use this call directly. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_serial_settings -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_serial_hs( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device provides the level of its inputs signal. - - This is useful to display the signal level of e.g. an IRIG or longwave signal. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @see @ref mbgdevio_fast_timestamp_fncs */ - _MBG_API_ATTR int _MBG_API mbg_dev_has_signal( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device provides a modulation signal. - - Modulation signals are e.g. the second marks of a DCF77 AM receiver. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - */ - _MBG_API_ATTR int _MBG_API mbg_dev_has_mod( MBG_DEV_HANDLE dh, int *p ) ; + _MBG_API_ATTR int _MBG_API mbg_get_fast_hr_timestamp( MBG_DEV_HANDLE dh, PCPS_TIME_STAMP *p ) ; /** - * @brief Check if a device provides either an IRIG input or output. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @brief Read current configuraton and features provided by the programmable pulse outputs. * - * @see ::mbg_dev_is_irig_rx - * @see ::mbg_dev_has_irig_tx - */ - _MBG_API_ATTR int _MBG_API mbg_dev_has_irig( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device provides a configurable ref time offset. - - This may be required to convert the received time to %UTC, if the input - signal doesn't specify this (e.g. most IRIG code formats). - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * Read a ::POUT_INFO_IDX array of current settings and configuration + * options of the device's programmable pulse outputs. + * + * A valid ::RECEIVER_INFO associated with the device + * has to be passed to this function. + * + * The function should only be called if the ::RECEIVER_INFO::n_prg_out + * field (i.e. the number of programmable outputs on the board) is not 0. + * + * The array passed to this function to receive the returned data + * must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] pii Pointer to a an array of ::POUT_INFO_IDX structures to be filled up + * @param[in] p_ri Pointer to the ::RECEIVER_INFO associated with the device //### TODO Make this obsolete + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_get_ref_offs - * @see ::mbg_set_ref_offs -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_ref_offs( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports the ::MBG_OPT_INFO/::MBG_OPT_SETTINGS. - - These structures containing optional settings, controlled by flags. - See ::MBG_OPT_SETTINGS and related definitions. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_opt_info - * @see ::mbg_set_opt_settings -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_opt_flags( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports large configuration data structures. - - Such structures have been introduced with the first Meinberg GPS receivers. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - */ - _MBG_API_ATTR int _MBG_API mbg_dev_has_gps_data( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device provides a programmable frequency synthesizer. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_synth - * @see ::mbg_set_synth -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_synth( MBG_DEV_HANDLE dh, int *p ) ; - - /* (Intentionally excluded from Doxygen) - * @brief Check if a device supports the mbg_generic_io() call. - - <b>Warning</b>: That call is for debugging purposes and internal use only! - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_generic_io() -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_generic_io( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports the mbg_get_asic_version() call. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_asic_version -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_asic_version( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports the mbg_get_asic_features() call. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_asic_features -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_asic_features( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Read current configuraton and features provided by the programmable pulse outputs. - - Reads a ::POUT_INFO_IDX array of current settings and configuration - options of the device's programmable pulse outputs. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - The function should only be called if the ::RECEIVER_INFO::n_prg_out - field (i.e. the number of programmable outputs on the board) is not 0. - - The array passed to this function to receive the returned data - must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pii Pointer to a an array of ::POUT_INFO_IDX structures to be filled up - @param *p_ri Pointer to a ::RECEIVER_INFO structure returned by mbg_setup_receiver_info() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - * @see ::mbg_set_gps_pout_settings_idx * @see ::mbg_set_gps_pout_settings * @see ::mbg_setup_receiver_info -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_pout_info( MBG_DEV_HANDLE dh, POUT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) ; /** * @brief Write the configuration for a single programmable pulse output - - The ::POUT_SETTINGS_IDX structure contains both the ::POUT_SETTINGS - and the output index value. Except for the parameter types this call - is equivalent to mbg_set_gps_pout_settings(). - - The function should only be called if the ::RECEIVER_INFO::n_prg_out field - (i.e. the number of programmable outputs on the board) is not 0, and the - output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::POUT_SETTINGS_IDX structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::POUT_SETTINGS_IDX structure contains both the ::POUT_SETTINGS + * and the output index value. Except for the parameter types this call + * is equivalent to ::mbg_set_gps_pout_settings. + * + * The function should only be called if the ::RECEIVER_INFO::n_prg_out field + * (i.e. the number of programmable outputs on the board) is not 0, and the + * output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::POUT_SETTINGS_IDX structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_gps_all_pout_info * @see ::mbg_set_gps_pout_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings_idx( MBG_DEV_HANDLE dh, const POUT_SETTINGS_IDX *p ) ; /** * @brief Write the configuration for a single programmable pulse output - - The ::POUT_SETTINGS structure does not contain the index of the - programmable output to be configured, so the index must explicitely - be passed to this function. Except for the parameter types this call - is equivalent to mbg_set_gps_pout_settings_idx(). - - The function should only be called if the ::RECEIVER_INFO::n_prg_out field - (i.e. the number of programmable outputs on the board) is not 0, and the - output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::POUT_SETTINGS structure to be written - @param idx Index of the programmable pulse output to be configured (starting from 0 ). - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * + * The ::POUT_SETTINGS structure does not contain the index of the + * programmable output to be configured, so the index must explicitly + * be passed to this function. Except for the parameter types this call + * is equivalent to ::mbg_set_gps_pout_settings_idx. + * + * The function should only be called if the ::RECEIVER_INFO::n_prg_out field + * (i.e. the number of programmable outputs on the board) is not 0, and the + * output index value must be in the range 0..::RECEIVER_INFO::n_prg_out. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::POUT_SETTINGS structure to be written. + * @param[in] idx Index of the programmable pulse output to be configured (starting from 0 ). + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_gps_all_pout_info * @see ::mbg_set_gps_pout_settings_idx -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_gps_pout_settings( MBG_DEV_HANDLE dh, const POUT_SETTINGS *p, int idx ) ; /** * @brief Read a device's IRQ status information. - - IRQ status information includes flags indicating whether IRQs are - actually enabled, and whether IRQ support by a card is possibly - unsafe due to the firmware and interface chip version. - + * + * IRQ status information includes flags indicating whether IRQs are + * actually enabled, and whether IRQ support by a card is possibly + * unsafe due to the firmware and interface chip version. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PCPS_IRQ_STAT_INFO variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[out] p Pointer to a ::PCPS_IRQ_STAT_INFO variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see @ref PCPS_IRQ_STAT_INFO_DEFS */ _MBG_API_ATTR int _MBG_API mbg_get_irq_stat_info( MBG_DEV_HANDLE dh, PCPS_IRQ_STAT_INFO *p ) ; /** - * @brief Check if a device provides simple LAN interface API calls. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_lan_if_info - * @see ::mbg_get_ip4_state - * @see ::mbg_get_ip4_settings - * @see ::mbg_set_ip4_settings -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_lan_intf( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Read LAN interface information from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - + * @brief Read LAN interface information from a device + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::LAN_IF_INFO variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @param[out] p Pointer to a ::LAN_IF_INFO variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_ip4_state * @see ::mbg_get_ip4_settings * @see ::mbg_set_ip4_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_lan_if_info( MBG_DEV_HANDLE dh, LAN_IF_INFO *p ) ; /** - * @brief Read LAN IPv4 state from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - + * @brief Read LAN IPv4 state from a device + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::IP4_SETTINGS variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @param[out] p Pointer to a ::IP4_SETTINGS variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_settings * @see ::mbg_set_ip4_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ip4_state( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) ; /** * @brief Read LAN IPv4 settings from a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::IP4_SETTINGS variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @param[out] p Pointer to a ::IP4_SETTINGS variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_state * @see ::mbg_set_ip4_settings - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ip4_settings( MBG_DEV_HANDLE dh, IP4_SETTINGS *p ) ; /** - * @brief Write LAN IPv4 settings to a device. - - The macro _pcps_has_lan_intf() or the API call mbg_dev_has_lan_intf() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p ::IP4_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_lan_intf + * @brief Write LAN IPv4 settings to a device + * + * The API call ::mbg_chk_dev_has_lan_intf checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p ::IP4_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_lan_intf * @see ::mbg_get_lan_if_info * @see ::mbg_get_ip4_settings -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_ip4_settings( MBG_DEV_HANDLE dh, const IP4_SETTINGS *p ) ; /** - * @brief Check if a device provides PTP configuration/status calls. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_all_ptp_cfg_info - * @see ::mbg_get_ptp_state - * @see ::mbg_get_ptp_cfg_info - * @see ::mbg_set_ptp_cfg_settings - * @see ::mbg_dev_has_ptp_unicast -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_ptp( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device provides PTP unicast feature/configuration. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_all_ptp_cfg_info - * @see ::mbg_get_ptp_uc_master_cfg_limits - * @see ::mbg_get_all_ptp_uc_master_info - * @see ::mbg_set_ptp_uc_master_settings_idx - * @see ::mbg_get_ptp_state -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_ptp_unicast( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Read PTP/IEEE1588 status from a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - + * @brief Read PTP/IEEE1588 status from a device + * + * The API call ::mbg_chk_dev_has_ptp checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PTP_STATE variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp + * @param[out] p Pointer to a ::PTP_STATE variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_cfg_info * @see ::mbg_set_ptp_cfg_settings - * @see ::mbg_dev_has_ptp_unicast - */ + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_state( MBG_DEV_HANDLE dh, PTP_STATE *p ) ; /** - * @brief Read PTP/IEEE1588 config info and current settings from a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - + * @brief Read PTP/IEEE1588 config info and current settings from a device + * + * The API call ::mbg_chk_dev_has_ptp checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PTP_CFG_INFO variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp + * @param[out] p Pointer to a ::PTP_CFG_INFO variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_state * @see ::mbg_set_ptp_cfg_settings - * @see ::mbg_dev_has_ptp_unicast - */ + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_cfg_info( MBG_DEV_HANDLE dh, PTP_CFG_INFO *p ) ; /** * @brief Write PTP/IEEE1588 configuration settings to a device. - - The macro _pcps_has_ptp() or the API call mbg_dev_has_ptp() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p ::PTP_CFG_SETTINGS structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp + * + * The API call ::mbg_chk_dev_has_ptp checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p ::PTP_CFG_SETTINGS structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_state * @see ::mbg_get_ptp_cfg_info - * @see ::mbg_dev_has_ptp_unicast -*/ + * @see ::mbg_chk_dev_has_ptp_unicast + */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_cfg_settings( MBG_DEV_HANDLE dh, const PTP_CFG_SETTINGS *p ) ; /** * @brief Read PTP/IEEE1588 unicast master configuration limits from a device. - - The macro _pcps_has_ri_ptp_unicast() or the API call mbg_dev_has_ptp_unicast() - check whether this call is supported by a device. - + * + * The API call ::mbg_chk_dev_has_ptp_unicast checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::PTP_UC_MASTER_CFG_LIMITS variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp_unicast + * @param[out] p Pointer to a ::PTP_UC_MASTER_CFG_LIMITS variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_all_ptp_uc_master_info * @see ::mbg_set_ptp_uc_master_settings_idx * @see ::mbg_get_ptp_state - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_ptp_uc_master_cfg_limits( MBG_DEV_HANDLE dh, PTP_UC_MASTER_CFG_LIMITS *p ) ; /** * @brief Read PTP Unicast master settings and configuration options. - - The function mbg_setup_receiver_info() must have been called before, - and the returned ::RECEIVER_INFO structure passed to this function. - The function should only be called if the ::RECEIVER_INFO::n_prg_out - field (i.e. the number of programmable outputs on the board) is not 0. - - The array passed to this function to receive the returned data - must be able to hold at least ::RECEIVER_INFO::n_prg_out elements. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param pii Pointer to a an array of ::PTP_UC_MASTER_INFO_IDX structures to be filled up - @param p_umsl Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure returned by mbg_get_ptp_uc_master_cfg_limits() - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp_unicast + * + * The array passed to this function to receive the returned data + * must be able to hold at least ::PTP_UC_MASTER_CFG_LIMITS::n_supp_master elements. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] pii Pointer to a an array of ::PTP_UC_MASTER_INFO_IDX structures to be filled up. + * @param[in] p_umsl Pointer to a ::PTP_UC_MASTER_CFG_LIMITS structure returned by ::mbg_get_ptp_uc_master_cfg_limits + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_uc_master_cfg_limits * @see ::mbg_set_ptp_uc_master_settings_idx * @see ::mbg_get_ptp_state -*/ + */ _MBG_API_ATTR int _MBG_API mbg_get_all_ptp_uc_master_info( MBG_DEV_HANDLE dh, PTP_UC_MASTER_INFO_IDX pii[], const PTP_UC_MASTER_CFG_LIMITS *p_umsl ) ; /** - * @brief Write PTP/IEEE1588 unicast configuration settings to a device. - - The macro _pcps_has_ri_ptp_unicast() or the API call mbg_dev_has_ptp_unicast() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p ::PTP_UC_MASTER_SETTINGS_IDX structure to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_ptp_unicast + * @brief Write PTP/IEEE1588 unicast configuration settings to a device + * + * The API call ::mbg_chk_dev_has_ptp_unicast checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p ::PTP_UC_MASTER_SETTINGS_IDX structure to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_ptp_unicast * @see ::mbg_get_all_ptp_cfg_info * @see ::mbg_get_ptp_uc_master_cfg_limits * @see ::mbg_get_all_ptp_uc_master_info * @see ::mbg_get_ptp_state -*/ + */ _MBG_API_ATTR int _MBG_API mbg_set_ptp_uc_master_settings_idx( MBG_DEV_HANDLE dh, const PTP_UC_MASTER_SETTINGS_IDX *p ) ; /** - * @brief Read both system time and associated device time from the kernel driver. - - The kernel driver reads the current system time plus a HR time structure - from a card immediately after each other. The returned info structure also - contains some cycles counts to be able to determine the execution times - required to read those time stamps. - - The advantage of this call compared to mbg_get_time_info_tstamp() is - that this call also returns the card's status. On the other hand, reading - the HR time from the card may block e.g. if another application accesses - the board. - - This call makes a mbg_get_hr_time_cycles() call internally so the macro - _pcps_has_hr_time() or the API call mbg_dev_has_hr_time() can be - used to check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_TIME_INFO_HRT variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_hr_time + * @brief Read both system time and associated device time from the kernel driver + * + * The kernel driver reads the current system time plus a HR time structure + * from a card immediately after each other. The returned info structure also + * contains some cycles counts to be able to determine the execution times + * required to read those time stamps. + * + * The advantage of this call compared to ::mbg_get_time_info_tstamp is + * that this call also returns the card's status. On the other hand, reading + * the HR time from the card may block e.g. if another application accesses + * the board. + * + * This call makes a ::mbg_get_hr_time_cycles call internally so the API call + * ::mbg_chk_dev_has_hr_time can be used to check whether this call is supported + * by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_TIME_INFO_HRT structure to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_hr_time * @see ::mbg_get_time_info_tstamp */ _MBG_API_ATTR int _MBG_API mbg_get_time_info_hrt( MBG_DEV_HANDLE dh, MBG_TIME_INFO_HRT *p ) ; /** - * @brief Read both system time and associated device timestamp from the kernel driver. - - This call is similar to mbg_get_time_info_hrt() except that a - mbg_get_fast_hr_timestamp_cycles() call is made internally, so the macro - _pcps_has_fast_hr_timestamp() or the API call mbg_dev_has_fast_hr_timestamp() - can be used to check whether this call is supported by a device. - + * @brief Read both system time and associated device timestamp from the kernel driver + * + * This call is similar to ::mbg_get_time_info_hrt except that a + * ::mbg_get_fast_hr_timestamp_cycles call is made internally, so + * the API call ::mbg_chk_dev_has_fast_hr_timestamp can be used to check whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_TIME_INFO_TSTAMP variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_fast_hr_timestamp + * @param[out] p Pointer to a ::MBG_TIME_INFO_TSTAMP structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_fast_hr_timestamp * @see ::mbg_get_time_info_hrt */ _MBG_API_ATTR int _MBG_API mbg_get_time_info_tstamp( MBG_DEV_HANDLE dh, MBG_TIME_INFO_TSTAMP *p ) ; /** - * @brief Check if a device supports demodulation of the DCF77 PZF code. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_corr_info - * @see ::mbg_dev_has_tr_distance -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_pzf( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports reading correlation info. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pzf - * @see ::mbg_get_corr_info -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_corr_info( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Check if a device supports configurable distance from transmitter. - - The distance from transmitter parameter is used to compensate - the RF propagation delay, mostly with long wave receivers. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pzf - * @see ::mbg_get_tr_distance - * @see ::mbg_set_tr_distance -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_tr_distance( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Read PZF correlation info from a device. - - The macro _pcps_has_corr_info() or the API call mbg_dev_has_corr_info() - check whether this call is supported by a device. - + * @brief Read PZF correlation info from a device + * + * The API call ::mbg_chk_dev_has_corr_info checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::CORR_INFO variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pzf - * @see ::mbg_dev_has_corr_info - */ + * @param[out] p Pointer to a ::CORR_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_has_corr_info + */ _MBG_API_ATTR int _MBG_API mbg_get_corr_info( MBG_DEV_HANDLE dh, CORR_INFO *p ) ; /** - * @brief Read configurable "distance from transmitter" parameter from a device. - - The distance from transmitter parameter is used to compensate - the RF propagation delay, mostly with long wave receivers. - - The macro _pcps_has_tr_distance() or the API call mbg_dev_has_tr_distance() - check whether this call is supported by a device. - + * @brief Read configurable "distance from transmitter" parameter from a device + * + * The distance from transmitter parameter is used to compensate + * the RF propagation delay, mostly with long wave receivers. + * + * The API call ::mbg_chk_dev_has_tr_distance checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TR_DISTANCE variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pzf - * @see ::mbg_dev_has_tr_distance + * @param[out] p Pointer to a ::TR_DISTANCE variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_has_tr_distance * @see ::mbg_set_tr_distance */ _MBG_API_ATTR int _MBG_API mbg_get_tr_distance( MBG_DEV_HANDLE dh, TR_DISTANCE *p ) ; /** * @brief Write configurable "distance from transmitter" parameter to a device. - - The distance from transmitter parameter is used to compensate - the RF propagation delay, mostly with long wave receivers. - - The macro _pcps_has_tr_distance() or the API call mbg_dev_has_tr_distance() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::TR_DISTANCE variable to be written - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_pzf - * @see ::mbg_dev_has_tr_distance + * + * The distance from transmitter parameter is used to compensate + * the RF propagation delay, mostly with long wave receivers. + * + * The API call ::mbg_chk_dev_has_tr_distance checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[in] p Pointer to a ::TR_DISTANCE variable to be written. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_pzf + * @see ::mbg_chk_dev_has_tr_distance * @see ::mbg_get_tr_distance - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_tr_distance( MBG_DEV_HANDLE dh, const TR_DISTANCE *p ) ; /** - * @brief Check if a device provides a debug status word to be read. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_get_debug_status -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_debug_status( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Read a debug status word from a device. - - This is mainly supported by IRIG timecode receiver cards, and the status - word is intended to provide more detailed information why a card might not - synchronize to the incoming timecode signal. - - See ::MBG_DEBUG_STATUS and related definitions for details. - - The macro _pcps_has_debug_status() or the API call mbg_dev_has_debug_status() - check whether this call is supported by a device. - + * @brief Read a debug status word from a device + * + * This is mainly supported by IRIG timecode receiver cards, and the status + * word is intended to provide more detailed information why a card might not + * synchronize to the incoming timecode signal. + * + * See ::MBG_DEBUG_STATUS and related definitions for details. + * + * The API call ::mbg_chk_dev_has_debug_status checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_DEBUG_STATUS variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_debug_status - */ + * @param[out] p Pointer to a ::MBG_DEBUG_STATUS variable to be filled up + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_debug_status + */ _MBG_API_ATTR int _MBG_API mbg_get_debug_status( MBG_DEV_HANDLE dh, MBG_DEBUG_STATUS *p ) ; /** - * @brief Check if a device provides an on-board event log. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_clr_evt_log - * @see ::mbg_get_num_evt_log_entries - * @see ::mbg_get_first_evt_log_entry - * @see ::mbg_get_next_evt_log_entry -*/ - _MBG_API_ATTR int _MBG_API mbg_dev_has_evt_log( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Clear the card's on-board event log. - - The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a device. - - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_evt_log + * @brief Clear the device's on-board event log + * + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_first_evt_log_entry * @see ::mbg_get_next_evt_log_entry - */ + */ _MBG_API_ATTR int _MBG_API mbg_clr_evt_log( MBG_DEV_HANDLE dh ) ; /** - * @brief Read details about a device's on-board event log buffer. - - The returned ::MBG_NUM_EVT_LOG_ENTRIES structure tells how many event log - entries which can be saved on the board, and how many entries actually - have been saved. - - The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - check whether this call is supported by a device. - + * @brief Read details about a device's on-board event log buffer + * + * The returned ::MBG_NUM_EVT_LOG_ENTRIES structure tells how many + * event log entries can be saved on the board, and how many entries + * actually have been saved. + * + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. + * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - @param *p Pointer to a ::MBG_NUM_EVT_LOG_ENTRIES variable to be filled up - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - - * @see ::mbg_dev_has_evt_log + * @param[out] p Pointer to a ::MBG_NUM_EVT_LOG_ENTRIES variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log * @see ::mbg_get_first_evt_log_entry * @see ::mbg_get_next_evt_log_entry - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_num_evt_log_entries( MBG_DEV_HANDLE dh, MBG_NUM_EVT_LOG_ENTRIES *p ) ; /** - * @brief Read the first (oldest) event log entry from a device. + * @brief Read the first (oldest) event log entry from a device * - * @note Subsequent reads should be made using mbg_get_next_evt_log_entry(). + * @note Subsequent reads should be made using ::mbg_get_next_evt_log_entry. * - * The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. * * If no (more) event log entry is available on the device then * the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up + * @param[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_evt_log + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_next_evt_log_entry @@ -3353,23 +5004,23 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_first_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ; /** - * @brief Read the next event log entry from a device. + * @brief Read the next event log entry from a device * - * @note The first read should be made using mbg_get_first_evt_log_entry() + * @note The first read should be made using ::mbg_get_first_evt_log_entry * to set the on-board read index to the oldest entry. * - * The macro _pcps_has_evt_log() or the API call mbg_dev_has_evt_log() - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_evt_log checks whether + * this call is supported by a device. * * If no (more) event log entry is available on the device then * the returned MBG_EVT_LOG_ENTRY::code is MBG_EVT_ID_NONE. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up + * @param[out] p Pointer to a ::MBG_EVT_LOG_ENTRY variable to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_evt_log + * @see ::mbg_chk_dev_has_evt_log * @see ::mbg_clr_evt_log * @see ::mbg_get_num_evt_log_entries * @see ::mbg_get_first_evt_log_entry @@ -3377,108 +5028,82 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_next_evt_log_entry( MBG_DEV_HANDLE dh, MBG_EVT_LOG_ENTRY *p ) ; /** - * @brief Check if a device supports GNSS configuration. - * - * This is usually the case if a device supports reception of - * several different satellite systems, e.g. GPS, Glonass, etc. - * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - * - * @see ::mbg_get_gps_gnss_mode_info - * @see ::mbg_set_gps_gnss_mode_settings - * @see ::mbg_get_gps_all_gnss_sat_info - */ - _MBG_API_ATTR int _MBG_API mbg_dev_is_gnss( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief Read the current GNSS mode info including current settings. + * @brief Read the current GNSS mode info including current settings * * The ::MBG_GNSS_MODE_INFO structure tells which GNSS systems are supported * by a device, and also includes the settings currently in effect. * - * The API call mbg_dev_is_gnss() can be used to check whether this call - * is supported by a device. See also the notes for mbg_dev_is_gnss(). + * The API call ::mbg_chk_dev_is_gnss can be used to check whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up + * See also the notes for ::mbg_chk_dev_is_gnss. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_set_gps_gnss_mode_settings * @see ::mbg_get_gps_all_gnss_sat_info - * @see ::mbg_dev_is_gnss + * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _MBG_API mbg_get_gps_gnss_mode_info( MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p_mi ) ; /** - * @brief Write the GNSS mode configuration to a device. + * @brief Write the GNSS mode configuration to a device * - * The ::MBG_GNSS_MODE_SETTINGS structure determines to configure the - * GNSS settings for a device, i.e. which satellite systems have to be used. + * The ::MBG_GNSS_MODE_SETTINGS structure determines the GNSS settings + * for a device, e.g. which satellite systems have to be used. * - * The function mbg_get_gps_gnss_mode_info() should have been called before + * The function ::mbg_get_gps_gnss_mode_info should have been called before * to determine which GNSS settings are supported by the device. * - * The API call mbg_dev_is_gnss() can be used to check whether these API calls - * are supported by a device. See also the notes for mbg_dev_is_gnss(). + * The API call ::mbg_chk_dev_is_gnss can be used to check whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p_ms Pointer to a ::MBG_GNSS_MODE_SETTINGS structure to be written + * See also the notes for ::mbg_chk_dev_is_gnss. + * + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p_ms Pointer to a ::MBG_GNSS_MODE_SETTINGS structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_gps_gnss_mode_info * @see ::mbg_get_gps_all_gnss_sat_info - * @see ::mbg_dev_is_gnss + * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _MBG_API mbg_set_gps_gnss_mode_settings( MBG_DEV_HANDLE dh, const MBG_GNSS_MODE_SETTINGS *p_ms ) ; /** - * @brief Read a ::GNSS_SAT_INFO_IDX array of satellite status information. + * @brief Read a ::GNSS_SAT_INFO_IDX array of satellite status information * - * The function mbg_get_gps_gnss_mode_info() must have been called before, - * and the returned ::MBG_GNSS_MODE_INFO structure passed to this function. + * The function ::mbg_get_gps_gnss_mode_info must have been called before, + * and the returned ::MBG_GNSS_MODE_INFO structure be passed to this function. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param gsii Pointer to a an array of satellite info structures to be filled up - * @param *p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure returned by mbg_get_gps_gnss_mode_info() + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] gsii Pointer to a an array of satellite info structures to be filled up. + * @param[in] p_mi Pointer to a ::MBG_GNSS_MODE_INFO structure returned by ::mbg_get_gps_gnss_mode_info. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * * @see ::mbg_get_gps_gnss_mode_info * @see ::mbg_set_gps_gnss_mode_settings - * @see ::mbg_dev_is_gnss + * @see ::mbg_chk_dev_is_gnss */ _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gnss_sat_info( MBG_DEV_HANDLE dh, GNSS_SAT_INFO_IDX gsii[], const MBG_GNSS_MODE_INFO *p_mi ) ; /** - * @brief Check if a device provides GPIO signal inputs and/or outputs - * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] *p Pointer to an int which is set 0 or != 0 unless the call fails. - * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - * - * @see ::mbg_dev_has_gpio - * @see ::mbg_get_gpio_cfg_limits - * @see ::mbg_get_gps_all_gpio_info - * @see ::mbg_set_gps_gpio_settings_idx - * @see ::mbg_get_gps_all_gpio_status - */ - _MBG_API_ATTR int _MBG_API mbg_dev_has_gpio( MBG_DEV_HANDLE dh, int *p ) ; - - /** * @brief Read common GPIO configuration limits * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] p A ::MBG_GPIO_CFG_LIMITS structure to be filled up + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p A ::MBG_GPIO_CFG_LIMITS structure to be filled up. * - * @see ::mbg_dev_has_gpio + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -3487,15 +5112,18 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gpio_cfg_limits( MBG_DEV_HANDLE dh, MBG_GPIO_CFG_LIMITS *p ) ; /** - * @brief Get all GPIO settings and capabilities + * @brief Get all GPIO settings and capabilities. + * + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] gii An array of ::MBG_GPIO_STATUS_IDX structures to be filled up - * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] gii An array of ::MBG_GPIO_STATUS_IDX structures to be filled up. + * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -3509,15 +5137,15 @@ extern "C" { * The ::MBG_GPIO_SETTINGS_IDX structure contains both the ::MBG_GPIO_SETTINGS * and the port index value. * - * The macro ::_pcps_has_ri_gpio or the API call ::mbg_dev_has_gpio - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_gpio checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] p Pointer to a ::MBG_GPIO_SETTINGS_IDX structure to be written + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::MBG_GPIO_SETTINGS_IDX structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -3528,13 +5156,13 @@ extern "C" { /** * @brief Read the status of all GPIO signal ports * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] gsi An array of ::MBG_GPIO_STATUS_IDX structures to be filled up - * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] gsi An array of ::MBG_GPIO_STATUS_IDX structures to be filled up. + * @param[in] p_gcl Pointer to a ::MBG_GPIO_CFG_LIMITS structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_gpio + * @see ::mbg_chk_dev_has_gpio * @see ::mbg_get_gpio_cfg_limits * @see ::mbg_get_gps_all_gpio_info * @see ::mbg_set_gps_gpio_settings_idx @@ -3542,30 +5170,14 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_gps_all_gpio_status( MBG_DEV_HANDLE dh, MBG_GPIO_STATUS_IDX gsi[], const MBG_GPIO_CFG_LIMITS *p_gcl ) ; /** - * @brief Check if a device provides extended multi ref (XMR) inputs - * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to an int which is set 0 or != 0 unless the call fails. - * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - * - * @see ::mbg_get_xmr_instances - * @see ::mbg_get_gps_all_xmr_status - * @see ::mbg_get_gps_all_xmr_info - * @see ::mbg_set_gps_xmr_settings_idx - * @see ::mbg_get_xmr_holdover_status - */ - _MBG_API_ATTR int _MBG_API mbg_dev_has_xmr( MBG_DEV_HANDLE dh, int *p ) ; - - /** - * @brief + * @brief Read ::XMULTI_REF_INSTANCES * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param[out] *p A ::XMULTI_REF_INSTANCES structure to be filled up + * @param[out] p A ::XMULTI_REF_INSTANCES structure to be filled up. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info * @see ::mbg_set_gps_xmr_settings_idx @@ -3576,13 +5188,13 @@ extern "C" { /** * @brief Read the status of all XMR sources * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] xmrsi An array of ::XMULTI_REF_STATUS_IDX structures to be filled up - * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] xmrsi An array of ::XMULTI_REF_STATUS_IDX structures to be filled up. + * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_info * @see ::mbg_set_gps_xmr_settings_idx @@ -3593,13 +5205,13 @@ extern "C" { /** * @brief Read all XMR settings and capabilities * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device - * @param[out] xmrii An array of ::XMULTI_REF_INFO_IDX structures to be filled up - * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] xmrii An array of ::XMULTI_REF_INFO_IDX structures to be filled up. + * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_set_gps_xmr_settings_idx @@ -3613,15 +5225,15 @@ extern "C" { * The ::XMULTI_REF_SETTINGS_IDX structure contains both the ::XMULTI_REF_SETTINGS * and the index value. * - * The macro ::_pcps_has_ri_xmr or the API call ::mbg_dev_has_xmr - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_xmr checks whether + * this call is supported by a device. * * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::XMULTI_REF_SETTINGS_IDX structure to be written + * @param[in] p Pointer to a ::XMULTI_REF_SETTINGS_IDX structure to be written. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info @@ -3632,19 +5244,16 @@ extern "C" { /** * @brief Read the current XMR holdover interval from a device * - * Read a ::SYNTH structure containing the configuration of an optional - * on-board programmable frequency synthesizer. - * - * The macro ::_pcps_has_ri_xmr or the API call ::mbg_dev_has_xmr - * check whether this call is supported by a device. + * The API call ::mbg_chk_dev_has_xmr checks whether + * this call is supported by a device. * - * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. - * @param *p Pointer to a ::XMR_HOLDOVER_INTV structure to be filled up - * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before + * @param[in] dh Valid ::MBG_DEV_HANDLE handle to a Meinberg device. + * @param[out] p Pointer to a ::XMR_HOLDOVER_INTV structure to be filled up. + * @param[in] p_xmri Pointer to a ::XMULTI_REF_INSTANCES structure read before. * - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES * - * @see ::mbg_dev_has_xmr + * @see ::mbg_chk_dev_has_xmr * @see ::mbg_get_xmr_instances * @see ::mbg_get_gps_all_xmr_status * @see ::mbg_get_gps_all_xmr_info @@ -3653,266 +5262,279 @@ extern "C" { _MBG_API_ATTR int _MBG_API mbg_get_xmr_holdover_status( MBG_DEV_HANDLE dh, XMR_HOLDOVER_STATUS *p, const XMULTI_REF_INSTANCES *p_xmri ) ; /** - * @brief Read the CPU affinity of a process. - - This means on which of the available CPUs or CPU cores the process can be executed. - - @param pid The process ID. - @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * @brief Read the CPU affinity of a process + * + * This means on which of the available CPUs or CPU cores + * a process may be executed. + * + * @param[in] pid The process ID. + * @param[out] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_set_process_affinity * @see ::mbg_set_current_process_affinity_to_cpu - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ; /** * @brief Set the CPU affinity of a process. - - This determines on which of the available CPUs - the process is allowed to be executed. - - @param pid The process ID. - @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * + * This determines on which of the available CPUs + * or CPU cores the process is allowed to be executed. + * + * @param[in] pid The process ID. + * @param[out] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_process_affinity * @see ::mbg_set_current_process_affinity_to_cpu - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_process_affinity( MBG_PROCESS_ID pid, MBG_CPU_SET *p ) ; /** - * @brief Set the CPU affinity of a process for a single CPU only. - - This means the process may only be executed on that single CPU. - - @param cpu_num The number of the CPU. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * @brief Set the CPU affinity of a process for a single CPU only + * + * This means the process may only be executed on that single CPU. + * + * @param[in] cpu_num The number of the CPU. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_process_affinity * @see ::mbg_set_process_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_set_current_process_affinity_to_cpu( int cpu_num ) ; /** * @brief Create a new execution thread for the current process. - - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure to be filled up. - @param fnc The name of the thread function to be started. - @param arg A generic argument passed to the thread function. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * + * This function is only implemented for targets that support threads. + * + * @param[in] p_ti Pointer to a ::MBG_THREAD_INFO structure to be filled up. + * @param[in] fnc The name of the thread function to be started. + * @param[in] arg A generic argument passed to the thread function. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_thread_stop * @see ::mbg_thread_sleep_interruptible * @see ::mbg_thread_set_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_create( MBG_THREAD_INFO *p_ti, MBG_THREAD_FNC fnc, void *arg ) ; /** - * @brief Stop a thread which has been created by mbg_thread_create(). - - Wait until the thread has finished and release all resources. - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * @brief Stop a thread which has been created by ::mbg_thread_create. + * + * Wait until the thread has finished and release all resources. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_thread_create * @see ::mbg_thread_sleep_interruptible * @see ::mbg_thread_set_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_stop( MBG_THREAD_INFO *p_ti ) ; /** - * @brief Let the current thread sleep for a certain interval. - - The sleep is interrupted if a signal is received indicating - the thread should terminate. - - This function is only implemented for targets which support threads. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - @param sleep_ms The number of milliseconds to sleep - * @return 0 if the sleep interval has expired normally - 1 if a signal to terminate has been received - <0 if an error has occurred - + * @brief Let the current thread sleep for a certain interval + * + * The sleep is interrupted if a signal is received indicating + * the thread should terminate. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. + * @param[in] sleep_ms The number of milliseconds to sleep + * + * @return MBG_SUCCESS if the sleep interval has expired normally, + * MBG_ERR_INTR if a signal to terminate has been received, + * or one of the other @ref MBG_ERROR_CODES + * * @see ::mbg_thread_create * @see ::mbg_thread_stop * @see ::mbg_thread_set_affinity - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_sleep_interruptible( MBG_THREAD_INFO *p_ti, ulong sleep_ms ) ; /** - * @brief Set the CPU affinity of a single thread. - - This determines on which of the available CPUs the thread - is allowed to be executed. - - This function is only implemented for targets which support thread affinity. - - @param p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. - @param *p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. - - * @return ::MBG_SUCCESS or error code returned by the system call. - + * @brief Set the CPU affinity of a single thread + * + * This determines on which of the available CPUs the thread + * is allowed to be executed. + * + * This function is only implemented for targets that support thread affinity. + * + * @param[in,out] p_ti Pointer to a ::MBG_THREAD_INFO structure associated with the thread. + * @param[in] p Pointer to a ::MBG_CPU_SET variable which contains a mask of CPUs. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_thread_create * @see ::mbg_thread_stop * @see ::mbg_thread_sleep_interruptible - */ + */ _MBG_API_ATTR int _MBG_API mbg_thread_set_affinity( MBG_THREAD_INFO *p_ti, MBG_CPU_SET *p ) ; /** - * @brief Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread. - - The new thread runs the mbg_xhrt_poll_thread_fnc() function. - - This function is only implemented for targets which support threads. - - @param *p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. - @param dh the handle of the device to be polled. - @param freq_hz The initial cycles frequency, if known, in Hz. - @param sleep_ms the sleep interval for the poll thread function in ms. - If this parameter is 0 then the default sleep interval is used. - + * @brief Set up a ::MBG_POLL_THREAD_INFO structure and start a new thread + * + * The new thread runs a function which periodically reads + * a time stamp / cycles pair from a device. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. + * @param[in] dh the Handle of the device to be polled. + * @param[in] freq_hz The initial cycles frequency, if known, in Hz. + * @param[in] sleep_ms the sleep interval for the poll thread function in ms. + * If this parameter is 0 then the default sleep interval is used. + * * @return ::MBG_SUCCESS on success, - ::MBG_ERR_NOT_SUPP_BY_DEV if the device to poll does not support HR time - else the result of mbg_thread_create() - + * ::MBG_ERR_NOT_SUPP_BY_DEV if the device to poll does not support HR time + * else the result of ::mbg_thread_create. + * * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_time_as_filetime * @see ::mbg_get_xhrt_cycles_frequency - */ + */ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_create( MBG_POLL_THREAD_INFO *p_pti, MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY freq_hz, int sleep_ms ) ; /** - * @brief Stop a polling thread started by mbg_xhrt_poll_thread_create(). - - This call also releases all associated resources. - - @param *p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. - - * @return the result of mbg_thread_stop() - + * @brief Stop a polling thread started by ::mbg_xhrt_poll_thread_create + * + * This call also releases all associated resources. + * + * @param[in,out] p_pti Pointer to a ::MBG_POLL_THREAD_INFO structure. + * + * @return The result of ::mbg_thread_stop. + * * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_time_as_filetime * @see ::mbg_get_xhrt_cycles_frequency - */ + */ _MBG_API_ATTR int _MBG_API mbg_xhrt_poll_thread_stop( MBG_POLL_THREAD_INFO *p_pti ) ; /** - * @brief Retrieve an extrapolated time stamp in PCPS_HR_TIME format. - - The time stamp is extrapolated using the system's current cycles counter value - and a time stamp plus associated cycles counter value saved by the polling thread. - See mbg_xhrt_poll_thread_fnc() for details and limitations. - - This function is only implemented for targets which support threads. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up. - - * @return MBG_SUCCESS or another return value from the polling thread's IOCTL call. - + * @brief Retrieve an extrapolated time stamp in ::PCPS_HR_TIME format + * + * The time stamp is extrapolated using the system's current cycles counter value + * and a time stamp plus associated cycles counter value saved by the polling thread. + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_filetime * @see ::mbg_get_xhrt_cycles_frequency - */ + * @see @ref mbg_xhrt_poll_group + */ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_pcps_hr_time( MBG_XHRT_INFO *p, PCPS_HR_TIME *p_hrt ) ; /** - * @brief Retrieve an extrapolated time stamp in FILETIME format. - - The time stamp is extrapolated using the system's current cycles counter value - and a time stamp plus associated cycles counter value saved by the polling thread. - See mbg_xhrt_poll_thread_fnc() for details and limitations. - - Since FILETIME is a Windows specific type this function is only - implemented under Windows. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_ft Pointer to a FILETIME structure to be filled up. - - * @return MBG_SUCCESS or another return value from the polling thread's IOCTL call. - + * @brief Retrieve an extrapolated time stamp in FILETIME format + * + * The time stamp is extrapolated using the system's current cycles counter value + * and a time stamp plus associated cycles counter value saved by the polling thread. + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * Since FILETIME is a Windows-specific type this function is only + * implemented under Windows. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_ft Pointer to a FILETIME structure to be filled up. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_cycles_frequency - */ + * @see @ref mbg_xhrt_poll_group + */ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_time_as_filetime( MBG_XHRT_INFO *p, FILETIME *p_ft ) ; /** - * @brief Retrieve the frequency of the system's cycles counter. - - The frequency is determined by the device polling thread. - See mbg_xhrt_poll_thread_fnc() for details and limitations. - - This function is only implemented for targets which support threads. - - @param *p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. - @param *p_freq_hz Pointer to a ::MBG_PC_CYCLES_FREQUENCY variable in which the frequency is returned. - * @return a status code from the polling thread: MBG_SUCCESS or an IOCTL error code. - + * @brief Retrieve the frequency of the system's cycles counter + * + * The frequency is determined by the device polling thread. + * See @ref mbg_xhrt_poll_group for details and limitations. + * + * This function is only implemented for targets that support threads. + * + * @param[in,out] p Pointer to a ::MBG_XHRT_INFO structure used to retrieve data from the polling thread. + * @param[out] p_freq_hz Pointer to a ::MBG_PC_CYCLES_FREQUENCY variable in which the frequency is returned. + * + * @return The return code from the API call used by the polling thread + * to read the time from the device, usually ::mbg_get_hr_time_cycles, + * so ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES. + * + * @ingroup mbg_xhrt_poll_group * @see ::mbg_xhrt_poll_thread_create * @see ::mbg_xhrt_poll_thread_stop * @see ::mbg_get_xhrt_time_as_pcps_hr_time * @see ::mbg_get_xhrt_time_as_filetime - */ + * @see @ref mbg_xhrt_poll_group + */ _MBG_API_ATTR int _MBG_API mbg_get_xhrt_cycles_frequency( MBG_XHRT_INFO *p, MBG_PC_CYCLES_FREQUENCY *p_freq_hz ) ; /** - * @brief Retrieve the default system's cycles counter frequency from the kernel driver. - - This API call can be used on systems which don't provide this information in user space. - - @param dh handle of the device to which the IOCTL call is sent. - @param *p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up. - - * @return ::MBG_SUCCESS on success, or one of the other @ref MBG_RETURN_CODES - + * @brief Retrieve the system's default cycles counter frequency from the kernel driver + * + * This API call can be used on systems which don't provide this information in user space. + * + * @param[in] dh Handle of the device to which the IOCTL call is sent. + * @param[out] p Pointer of a ::MBG_PC_CYCLES_FREQUENCY variable to be filled up. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * * @see ::mbg_get_default_cycles_frequency - */ + */ _MBG_API_ATTR int _MBG_API mbg_get_default_cycles_frequency_from_dev( MBG_DEV_HANDLE dh, MBG_PC_CYCLES_FREQUENCY *p ) ; /** - @brief Retrieve the system's default cycles counter frequency. - - @note This may not be supported on all target platforms, in which case the - returned frequency is 0 and the mbg_get_default_cycles_frequency_from_dev() - call should be used. - - @return the default cycles counter frequency in Hz, or 0 if the value is not available. - + * @brief Retrieve the system's default cycles counter frequency + * + * @note This may not be supported on all target platforms, in which case the + * returned frequency is 0 and the ::mbg_get_default_cycles_frequency_from_dev + * call should be used instead. + * + * @return the default cycles counter frequency in Hz, or 0 if the value is not available. + * * @see ::mbg_get_default_cycles_frequency_from_dev -*/ + */ _MBG_API_ATTR MBG_PC_CYCLES_FREQUENCY _MBG_API mbg_get_default_cycles_frequency( void ) ; /* ----- function prototypes end ----- */ -#ifdef __cplusplus -} -#endif - #if defined( MBG_TGT_WIN32 ) static __mbg_inline -MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, +MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, const void *in_p, int in_sz, void *out_p, int out_sz ) { - DWORD ReturnedLength; + DWORD ReturnedLength = 0; if ( !DeviceIoControl( dh, ioctl_code, (LPVOID) in_p, in_sz, out_p, out_sz, @@ -3920,18 +5542,19 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, NULL ) ) { - DWORD rc = GetLastError(); - -#if 0 //##++++++++++++++++++++++++ -// We can't call mbgsvctl_log_mbgdevio_error() here (for now). -// Is is defined in mbgsvctl.h, and including mbgsvc.h here, -// or copying the prototype here results in DLL import/export -// mismatch errors. - - // do not report a USB device timeout error - if ( rc != MBG_ERR_USB_ACCESS ) - mbgsvctl_log_mbgdevio_error( ioctl_code, rc ); -#endif + DWORD last_error = GetLastError(); + int rc = mbg_win32_sys_err_to_mbg( last_error, NULL ); + + #if 0 //### TODO FIXME + // We can't call mbgsvctl_log_mbgdevio_error() here (for now). + // Is is defined in mbgsvctl.h, and including mbgsvctl.h here, + // or copying the prototype here results in DLL import/export + // mismatch errors. + + // do not report a USB device timeout error + if ( rc != MBG_ERR_USB_ACCESS ) + mbgsvctl_log_mbgdevio_error( ioctl_code, rc ); + #endif return rc; } @@ -3943,10 +5566,36 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #define _do_mbg_ioctl( _dh, _ioctl, _p, _in_sz, _out_sz ) \ do_mbg_ioctl( _dh, _ioctl, (LPVOID) _p, _in_sz, (LPVOID) _p, _out_sz ) -#elif defined( MBG_HAS_UNIX_IOCTL ) +#elif defined( MBG_HAS_POSIX_IOCTL ) + + // In case of an error ioctl returns -1, and errno has been set + // to a *positive* POSIX error code. + + static __mbg_inline + MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, unsigned long ioctl_code, const void *p ) + { + int sys_rc = ioctl( dh, ioctl_code, (void *) p ); + + if ( sys_rc == -1 ) // error + { + int sys_errno = errno; + int rc = mbg_posix_errno_to_mbg( sys_errno, NULL ); + + #if DEBUG_IOCTL_CALLS + fprintf( stderr, "IOCTL %s (0x%08lX) error: %s (errno: %i) --> %s (rc: %i)\n", + mbgioctl_get_name( ioctl_code ), (ulong) ioctl_code, + strerror( sys_errno ), sys_errno, + mbg_strerror( rc ), rc ); + #endif + + return rc; + } + + return MBG_SUCCESS; + } #define _do_mbg_ioctl( _dh, _ioctl, _p, _in_sz, _out_sz ) \ - ioctl( _dh, _ioctl, _p ) + do_mbg_ioctl( _dh, _ioctl, _p ) #endif @@ -3955,33 +5604,33 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, // The code below depends on whether the target device is accessed via // IOCTLs to a device driver, or the hardware is accessed directly. -#if defined( MBG_USE_KERNEL_DRIVER ) // using IOCTL to access device driver - -/** - @brief Send a generic IOCTL command to the driver. - - @param dh Valid handle to a Meinberg device - @param info Additional information for the kernel driver depending on - the IOCTL code, i.e. the low level function to be called: <br> - one of the PCPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}<br> - one of the PC_GPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}_GPS<br> - one of the PCPS_GEN_IO_... enumeration codes with IOCTL_PCPS_GENERIC_IO - @param ioctl_code One of the IOCTL_GENERIC_... codes telling the kernel driver - which low level function to use, e.g. normal read or write, - large (GPS) data read or write, or generic I/O. - @param in_p Pointer to an input buffer passed to the driver, can be NULL - @param in_sz Size of the input buffer, can be 0 if no buffer is used - @param out_p Pointer to an output buffer passed to the driver, can be NULL - @param out_sz Size of the output buffer, can be 0 if no buffer is used - - @return ::MBG_SUCCESS or error code returned by device I/O control function. -*/ +#if MBG_TGT_USE_IOCTL + + /** + * @brief Send a generic IOCTL command to the driver. + * + * @param dh Valid handle to a Meinberg device + * @param info Additional information for the kernel driver depending on + * the IOCTL code, i.e. the low level function to be called: <br> + * one of the PCPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}<br> + * one of the PC_GPS_... commands with IOCTL_PCPS_GENERIC_{READ|WRITE}_GPS<br> + * one of the PCPS_GEN_IO_... enumeration codes with IOCTL_PCPS_GENERIC_IO + * @param ioctl_code One of the IOCTL_GENERIC_... codes telling the kernel driver + * which low level function to use, e.g. normal read or write, + * large (GPS) data read or write, or generic I/O. + * @param in_p Pointer to an input buffer passed to the driver, can be NULL + * @param in_sz Size of the input buffer, can be 0 if no buffer is used + * @param out_p Pointer to an output buffer passed to the driver, can be NULL + * @param out_sz Size of the output buffer, can be 0 if no buffer is used + * + * @return ::MBG_SUCCESS or error code returned by device I/O control function. + */ static __mbg_inline int mbgdevio_do_gen_io( MBG_DEV_HANDLE dh, int info, unsigned int ioctl_code, const void *in_p, int in_sz, void *out_p, int out_sz ) { - _mbgdevio_vars(); + MBGDEVIO_RET_VAL rc; // Generic IOCTL calls always need to pass some info beside // the I/O buffers down to the driver, which usually is @@ -3994,11 +5643,16 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, IOCTL_GENERIC_REQ req = { 0 }; - req.info = info; - req.in_p = in_p; + req.in_p = (uintptr_t) in_p; + req.out_p = (uintptr_t) out_p; req.in_sz = in_sz; - req.out_p = out_p; req.out_sz = out_sz; + req.info = info; + + #if DEBUG_IOCTL_CALLS + printf( "inp: %p --> 0x%" PRIx64 " (%lu)\n", in_p, req.in_p, (ulong) req.in_sz ); + printf( "outp: %p --> 0x%" PRIx64 " (%lu)\n", out_p, req.out_p, (ulong) req.out_sz ); + #endif rc = _do_mbg_ioctl( dh, ioctl_code, &req, sizeof( req ), 0 ); @@ -4031,7 +5685,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #endif - return _mbgdevio_ret_val; + return _mbgdevio_cnv_ret_val( rc ); } // mbgdevio_do_gen_io @@ -4081,7 +5735,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, mbgdevio_do_gen_io( _dh, _cmd, IOCTL_PCPS_GENERIC_WRITE_GPS, _p, _sz, NULL, 0 ) -#else // accessing hardware device directly +#else // !MBG_TGT_USE_IOCTL, accessing hardware device directly #define _mbgdevio_chk_cond( _cond ) \ { \ @@ -4135,7 +5789,7 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, #define _mbgdevio_gen_write_gps( _dh, _cmd, _p, _sz ) \ _mbgdevio_write_gps( _dh, _cmd, -1, _p, _sz ) -#endif +#endif // !MBG_TGT_USE_IOCTL @@ -4167,38 +5821,52 @@ MBGDEVIO_RET_VAL do_mbg_ioctl( MBG_DEV_HANDLE dh, int ioctl_code, -#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_UNIX ) +#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) + +// NOTE +// For some reason the code below causes an internal compiler error +// with Borland C++Builder 5.0 release builds. Since we don't need +// this function in the BC5 projects anyway we simply exclude it +// from build. + +#if !defined( __BORLANDC__ ) static __mbg_inline void mbg_chk_tstamp64_leap_sec( uint64_t *tstamp64, PCPS_TIME_STATUS_X *status ) { if ( *status & ( PCPS_LS_ANN | PCPS_LS_ENB ) ) { - time_t t = (uint32_t) ( *tstamp64 >> 32 ); - struct tm tm = *gmtime( &t ); + struct tm tm = { 0 }; + time_t t = cvt_to_time_t( (uint32_t) ( (*tstamp64) >> 32 ) ); + int rc = mbg_gmtime( &tm, &t ); - // Handle leap second and status - if ( tm.tm_hour == 0 && tm.tm_min == 0 && tm.tm_sec == 0 ) + if ( mbg_rc_is_success( rc ) ) { - if ( *status & PCPS_LS_ANN ) + // Handle leap second and status + if ( tm.tm_hour == 0 && tm.tm_min == 0 && tm.tm_sec == 0 ) { - // Set leap second enabled flag on rollover to the leap second and clear announce flag - *status &= ~PCPS_LS_ANN; - *status |= PCPS_LS_ENB; - - // Decrement interpolated second to avoid automated overflow during the leap second. - // Second 59 appears for the second time. - *tstamp64 -= PCPS_HRT_BIN_FRAC_SCALE; + if ( *status & PCPS_LS_ANN ) + { + // Set leap second enabled flag on rollover to the leap second and clear announce flag + *status &= ~PCPS_LS_ANN; + *status |= PCPS_LS_ENB; + + // Decrement interpolated second to avoid automated overflow during the leap second. + // Second 59 appears for the second time. + *tstamp64 -= MBG_FRAC32_UNITS_PER_SEC; + } + else + if ( *status & PCPS_LS_ENB ) // Clear bits when leap second expires and 0:00:00 UTC is reached + *status &= ~( PCPS_LS_ANN | PCPS_LS_ENB ); } - else - if ( *status & PCPS_LS_ENB ) // Clear bits when leap second expires and 0:00:00 UTC is reached - *status &= ~( PCPS_LS_ANN | PCPS_LS_ENB ); } } } // mbg_chk_tstamp64_leap_sec -#endif // defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_UNIX ) +#endif // !defined( __BORLANDC__ ) + +#endif // defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) @@ -4234,6 +5902,10 @@ void uint64_to_pcps_time_stamp( PCPS_TIME_STAMP *ts, uint64_t n ) #endif +#ifdef __cplusplus +} +#endif + #if defined( _USING_BYTE_ALIGNMENT ) #pragma pack() // set default alignment #undef _USING_BYTE_ALIGNMENT @@ -4243,6 +5915,7 @@ void uint64_to_pcps_time_stamp( PCPS_TIME_STAMP *ts, uint64_t n ) #undef _ext +#undef _DO_INIT #endif /* _MBGDEVIO_H */ diff --git a/c/mbglib/include/mbgerror.h b/c/mbglib/include/mbgerror.h index 10d0aa6..7641115 100644 --- a/c/mbglib/include/mbgerror.h +++ b/c/mbglib/include/mbgerror.h @@ -1,18 +1,77 @@ /************************************************************************** * - * $Id: mbgerror.h 1.7.1.1 2014/06/25 08:52:50Z martin TRASH $ + * $Id: mbgerror.h 1.25 2019/10/09 09:31:04Z philipp TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * * Description: - * Error codes used with Meinberg devices and drivers. - * The codes can be translated into an OS dependent error code. + * Common error codes used with Meinberg API calls. + * OS-specific error codes can be translated into these codes. * * ----------------------------------------------------------------------- * $Log: mbgerror.h $ - * Revision 1.7.1.1 2014/06/25 08:52:50Z martin - * Re-enabled some symbols which have been commented out.. + * Revision 1.25 2019/10/09 09:31:04Z philipp + * Added MBG_ERR_INV_USER and MBG_ERR_INV_GROUP + * Revision 1.24 2019/08/28 08:02:56 philipp + * Added error code MBG_ERR_IN_PROGRESS + * Revision 1.23 2019/08/26 15:14:34 martin + * Modified msg. text for MBG_ERR_NO_DATA. + * Revision 1.22 2019/08/20 08:20:04 martin + * Fixed build using mingw. + * Changed message text for MBG_ERR_ACCESS, which may also indicate that + * an exclusive resource is in use, not only that permissions are missing. + * Revision 1.21 2019/03/13 16:17:10 martin + * New code MBG_ERR_BAD_ADDRESS (for EFAULT). + * Revision 1.20 2019/03/13 09:44:30 martin + * Moved predefined program exit codes here. + * Revision 1.19 2019/02/08 10:42:56 martin + * Distinguish more detailed if an NTSTATUS replacement + * is required for a particular build environment. + * Revision 1.18 2018/11/22 11:25:56 martin + * New error code MBG_ERR_STR_SUBSTR merged from 1.15.1.x branch. + * Refactored surrogate definitions. + * Updated function prototypes. + * Revision 1.17 2018/09/21 09:49:57 martin + * Renamed MBG_ERR_FIFO to MBG_ERR_NO_DATA. + * Added strings for MBG_ERR_NO_DRIVER and MBG_ERR_DRV_VERSION. + * New code MBG_ERR_BUFFER_TOO_SMALL. + * MBG_ERR_OUTDATED error code added by philipp. + * Added some Windows stuff. + * Updated function prototypes. + * Revision 1.16 2018/06/25 14:26:38Z martin + * Some new error codes were introduced. + * New macro mbg_rc_is_success_or_err_perm(). + * New control macro _USE_WIN32_PRIVATE_STATUS_CODES. + * Split table initializers for error strings into two + * separate initializers to avoid overhead on target + * systems which don't support extended functions. + * Updated comments, string tables, and function prototypes. + * Revision 1.15 2017/07/05 09:27:25 martin + * New error code MBG_ERR_PARM_FMT. + * Changed message text for MBG_ERR_NO_ENTITY. + * Replaced old _mbg_err_to_os() macro by new inline functions + * mbg_errno_to_os() and mbg_ret_val_to_os(). + * Fixed build under Windows. + * Updated doxygen comments. + * Updated function prototypes. + * Revision 1.14 2017/05/10 15:21:39 martin + * Tiny cleanup. + * Revision 1.13 2017/02/28 15:23:14 gregoire + * error code MBG_ERR_INV_IDX added + * Revision 1.12 2017/01/10 15:54:56 philipp + * Fixed syntax error + * Revision 1.11 2017/01/10 14:26:31 philipp + * Added error MBG_ERR_NOT_CONFIGURED + * Revision 1.10 2016/12/16 12:40:33 thomas-b + * Added MBG_ERR_NO_SPACE + * Revision 1.9 2016/10/31 17:41:55 martin + * New error code MBG_ERR_DATA_FMT. + * Revision 1.8 2016/08/05 12:29:20 martin + * Re-enabled some symbols which have been commented out. + * Added new codes, and initializers for code/string conversion tables. + * Updated doxygen comments. + * Updated function prorotypes. * Revision 1.7 2014/05/27 13:32:47Z martin * Defined additional common error codes which can be * translated from OS specific codes. @@ -45,6 +104,58 @@ /* Other headers to be included */ #include <mbg_tgt.h> +#include <words.h> + +// We may need surrogate declarations for target-specific +// types that are used in common function prototypes. +// Without such declarations we'd get compiler errors +// on targets that don't have them. + +#if defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) + + #define MBG_TGT_MISSING_DWORD 1 // missing even in kernel space. + #define MBG_TGT_MISSING_NTSTATUS 0 // available in kernel space + + #else // Windows user space + + #define MBG_TGT_MISSING_DWORD 0 // available in user space + + // Some (but not all) Windows build environments provide a + // bcrypt.h file which has a definition for NTSTATUS, so we + // use.that if available to avoid duplicate / mismatching + // definitions in case an application uses bcrypt.h anyway. + #if !defined( MBG_TGT_HAS_BCRYPT_H ) // unless already defined elsewhere + #if defined( _MSC_VER ) && ( _MSC_VER >= 1500 ) // at least VS2008 has it + #define MBG_TGT_HAS_BCRYPT_H 1 + #endif + + #if defined( MBG_TGT_MINGW ) // older versions may not have it, though + #define MBG_TGT_HAS_BCRYPT_H 1 + #endif + + #if !defined( MBG_TGT_HAS_BCRYPT_H ) + #define MBG_TGT_HAS_BCRYPT_H 0 + #endif + #endif + + #if MBG_TGT_HAS_BCRYPT_H + #include <bcrypt.h> + #define MBG_TGT_MISSING_NTSTATUS 0 + #else + #define MBG_TGT_MISSING_NTSTATUS 1 + #endif + + #endif + +#else // non-Windows targets + + #define MBG_TGT_MISSING_DWORD 1 + #define MBG_TGT_MISSING_NTSTATUS 1 + +#endif + #ifdef _MBGERROR #define _ext @@ -56,111 +167,251 @@ /* Start of header body */ -#if !defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_KERNEL ) - //##++++ Surprisingly we need this also for Windows - // in kernel mode. This should be fixed. - #define DWORD uint32_t // just to avoid compiler errors +#ifdef __cplusplus +extern "C" { +#endif + +#if defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) + #define MBG_SYS_RC_SUCCESS STATUS_SUCCESS + #else + #define MBG_SYS_RC_SUCCESS ERROR_SUCCESS + #endif + +#elif defined( MBG_TGT_POSIX ) + + #define MBG_SYS_RC_SUCCESS 0 + +#else + + #define MBG_SYS_RC_SUCCESS 0 + +#endif + + +#if !defined( _USE_WIN32_PRIVATE_STATUS_CODES ) // FIXME + #define _USE_WIN32_PRIVATE_STATUS_CODES 0 +#endif + + +#if defined( MBG_TGT_WIN32 ) + +#define STATUS_SEVERITY_SUCCESS 0x0 +#define STATUS_SEVERITY_INFORMATIONAL 0x1 +#define STATUS_SEVERITY_WARNING 0x2 +#define STATUS_SEVERITY_ERROR 0x3 + +#define STATUS_SEVERITY_SHIFT_BITS 30 +#define STATUS_SEVERITY_SHIFT_MASK 0x03 + +#define STATUS_SEVERITY_SUCCESS_MASK ( STATUS_SEVERITY_SUCCESS << STATUS_SEVERITY_SHIFT_BITS ) +#define STATUS_SEVERITY_INFORMATIONAL_MASK ( STATUS_SEVERITY_INFORMATIONAL << STATUS_SEVERITY_SHIFT_BITS ) +#define STATUS_SEVERITY_WARNING_MASK ( STATUS_SEVERITY_WARNING << STATUS_SEVERITY_SHIFT_BITS ) +#define STATUS_SEVERITY_ERROR_MASK ( STATUS_SEVERITY_ERROR << STATUS_SEVERITY_SHIFT_BITS ) + +#define _get_win_msg_severity( _st ) ( ( (_st) >> STATUS_SEVERITY_SHIFT_BITS ) & STATUS_SEVERITY_SHIFT_MASK ) + + + +#define STATUS_CUSTOM_FLAG 0x1 + +#define STATUS_CUSTOM_FLAG_SHIFT_BITS 29 +#define STATUS_CUSTOM_FLAG_SHIFT_MASK 0x01 + +#define STATUS_CUSTOM_FLAG_MASK ( STATUS_CUSTOM_FLAG << STATUS_CUSTOM_FLAG_SHIFT_BITS ) + +#define _get_win_msg_custom_flag( _st ) ( ( (_st) >> STATUS_CUSTOM_FLAG_SHIFT_BITS ) & STATUS_CUSTOM_FLAG_SHIFT_MASK ) + +#define _win_msg_is_custom( _st ) ( _get_win_msg_custom_flag( _st ) != 0 ) + + +#define _mbg_msg_id_inf( num ) ((DWORD) ( STATUS_SEVERITY_INFORMATIONAL_MASK | STATUS_CUSTOM_FLAG_MASK | num ) ) +#define _mbg_msg_id_wrn( num ) ((DWORD) ( STATUS_SEVERITY_WARNING_MASK | STATUS_CUSTOM_FLAG_MASK | num ) ) +#define _mbg_msg_id_err( num ) ((DWORD) ( STATUS_SEVERITY_ERROR_MASK | STATUS_CUSTOM_FLAG_MASK | num ) ) + +#endif // defined( MBG_TGT_WIN32 ) + + + +#if MBG_TGT_MISSING_DWORD + typedef uint32_t DWORD; + #define DWORD DWORD +#endif + +#if MBG_TGT_MISSING_NTSTATUS + // We intentionally define an uncommon type to + // enforce build errors in case NTSTATUS is really + // used on targets that should not use it. + typedef int *NTSTATUS; + #define NTSTATUS NTSTATUS #endif + /** * @brief Error codes used with Meinberg devices and drivers * - * Some of the codes have to match codes which are defined in pcpsdefs.h - * and returned by the firmware of bus-level devices. - * - * The codes will be translated into an OS dependent error code - * when returned to the calling function. - * - * For Windows, these codes are made positive and or'ed with 0xE0000000 afterwards. + * Appropriate error strings can be retrieved via the ::mbg_strerror function. * - * Example: Code -19 (#MBG_ERR_GENERIC) will be converted to 0xE0000013 under Windows. - * - * @note Attention: - * The error codes below must match exactly the corresponding codes that are evaluated in user space. - * For Windows, they are located in messages.mc/.h in mbgsvctl.dll + * @see ::MBG_ERR_STR_TABLE_ENG * * @anchor MBG_RETURN_CODES @{ */ -#define MBG_SUCCESS 0 ///< no error, must match ::PCPS_SUCCESS +/* ### TODO FIXME + * Under Windows, some message strings are provided as resources appended + * to the mbgctrl DLL, but the codes specified here have to be translated + * to Windows-specific message IDs before the appropriate resource string + * can be retrieved. Actually this is done by taking the absolute number + * of an error code and have it or'ed with 0xE0000000 afterwards, e.g. + * ::MBG_ERR_GENERIC (-19) will yield Windows code 0xE0000013. + * * See ::_mbg_err_to_os + */ + +// NOTE: Some of these codes have to match codes which are defined in pcpsdefs.h +// and returned by the firmware of bus-level devices, so the definitions +// must *not* be renumbered. + +#define MBG_SUCCESS 0 ///< No error, has to match ::PCPS_SUCCESS /** @anchor MBG_ERROR_CODES @{ */ // Other codes which have to match codes defined in pcpsdefs.h returned by bus-level devices -#define MBG_ERR_STIME -1 ///< invalid date/time/status passed, must match ::PCPS_ERR_STIME -#define MBG_ERR_CFG -2 ///< invalid params with a configuration cmd, must match ::PCPS_ERR_CFG +#define MBG_ERR_STIME -1 ///< Tried to write invalid date/time/status to device, has to match ::PCPS_ERR_STIME +#define MBG_ERR_CFG -2 ///< Tried to write invalid configuration parameters to device, has to match ::PCPS_ERR_CFG (see also ::MBG_ERR_INV_CFG) // Codes returned by low level functions of the bus-level device driver -#define MBG_ERR_GENERIC -19 ///< generic error -#define MBG_ERR_TIMEOUT -20 ///< timeout accessing the device -#define MBG_ERR_FW_ID -21 ///< invalid firmware ID -#define MBG_ERR_NBYTES -22 ///< the number of parameter bytes passed to the device did not - ///< match the number of bytes expected by the device +#define MBG_ERR_GENERIC -19 ///< Generic error. +#define MBG_ERR_TIMEOUT -20 ///< Timeout accessing the device. +#define MBG_ERR_FW_ID -21 ///< Invalid firmware ID. +#define MBG_ERR_NBYTES -22 ///< The number of parameter bytes passed to the device did not + ///< match the number of bytes expected by the device. -#define MBG_ERR_INV_TIME -23 ///< the device doesn't have valid time -#define MBG_ERR_FIFO -24 ///< the data FIFO of a bus-level device is empty, though it shouldn't be -#define MBG_ERR_NOT_READY -25 ///< bus-level device is temp. unable to respond e.g. during init. after RESET -#define MBG_ERR_INV_TYPE -26 ///< bus-level device didn't recognize data type +#define MBG_ERR_INV_TIME -23 ///< The device has no valid time. +#define MBG_ERR_NO_DATA -24 ///< No (more) data to process, e.g. FIFO empty. +#define MBG_ERR_NOT_READY -25 ///< Bus-level device is temp. unable to respond e.g. during init. after RESET. +#define MBG_ERR_INV_TYPE -26 ///< Bus-level device didn't recognize data type. // Codes returned by the high level API functions -#define MBG_ERR_NO_MEM -27 ///< failed to allocate memory -#define MBG_ERR_CLAIM_RSRC -28 ///< failed to claim port or mem resource -#define MBG_ERR_DEV_NOT_SUPP -29 ///< specified device type not supported by driver -#define MBG_ERR_INV_DEV_REQUEST -30 ///< IOCTL call not supported by driver -#define MBG_ERR_NOT_SUPP_BY_DEV -31 ///< cmd or feature not supported by device -#define MBG_ERR_USB_ACCESS -32 ///< USB access failed -#define MBG_ERR_CYCLIC_TIMEOUT -33 ///< cyclic event (IRQ, etc.) didn't occur -#define MBG_ERR_NOT_SUPP_ON_OS -34 ///< function is not supported under this operating system -#define MBG_ERR_LIB_NOT_COMPATIBLE -35 ///< installed shared lib. version not compat. with version used at build time -#define MBG_ERR_N_COM_EXCEEDS_SUPP -36 ///< num. COM ports of the device exceeds max. supp. by driver -#define MBG_ERR_N_STR_EXCEEDS_SUPP -37 ///< num. string formats of the device exceeds max. supp. by driver -#define MBG_ERR_IRQ_UNSAFE -38 ///< enabled IRQ of bus-level device is unsafe with this firmware/ASIC version -#define MBG_ERR_N_POUT_EXCEEDS_SUPP -39 ///< num. prog. outputs of the device exceeds max. supp. by driver +#define MBG_ERR_NO_MEM -27 ///< Failed to allocate memory. +#define MBG_ERR_CLAIM_RSRC -28 ///< Failed to claim port or mem resource. +#define MBG_ERR_DEV_NOT_SUPP -29 ///< Device type not supported by driver. +#define MBG_ERR_INV_DEV_REQUEST -30 ///< IOCTL call not supported by driver. +#define MBG_ERR_NOT_SUPP_BY_DEV -31 ///< Command or feature not supported by device. +// #define MBG_ERR_USB_ACCESS -32 ///< USB access failed (FIXME TODO this is B.S., we should return *why*) +#define MBG_ERR_CYCLIC_TIMEOUT -33 ///< Cyclic event (IRQ, etc.) didn't occur in time. +#define MBG_ERR_NOT_SUPP_ON_OS -34 ///< Function is not supported on this operating system. +#define MBG_ERR_LIB_NOT_COMPATIBLE -35 ///< Installed shared library version not compatible with version used at build time. +#define MBG_ERR_N_COM_EXCEEDS_SUPP -36 ///< Num. COM ports of the device exceeds max. supp. by driver. +#define MBG_ERR_N_STR_EXCEEDS_SUPP -37 ///< Num. string formats of the device exceeds max. supp. by driver. +#define MBG_ERR_IRQ_UNSAFE -38 ///< Enabled IRQ of bus-level device is unsafe with this firmware/ASIC version. +#define MBG_ERR_N_POUT_EXCEEDS_SUPP -39 ///< Num. prog. outputs of the device exceeds max. supp. by driver. // Legacy codes used with DOS TSRs only: -#define MBG_ERR_INV_INTNO -40 ///< invalid interrupt number -#define MBG_ERR_NO_DRIVER -41 ///< a driver could not be found -#define MBG_ERR_DRV_VERSION -42 ///< the driver is too old +#define MBG_ERR_INV_INTNO -40 ///< Invalid interrupt number. +#define MBG_ERR_NO_DRIVER -41 ///< No driver could be found. +#define MBG_ERR_DRV_VERSION -42 ///< The driver is too old. -#define MBG_ERR_COPY_TO_USER -43 ///< kernel driver failed to copy data from kernel to user space -#define MBG_ERR_COPY_FROM_USER -44 ///< kernel driver failed to copy data from use to kernel space +#define MBG_ERR_COPY_TO_USER -43 ///< Kernel driver failed to copy data from kernel to user space. +#define MBG_ERR_COPY_FROM_USER -44 ///< Kernel driver failed to copy data from use to kernel space. // More codes returned by the driver's high level functions: -#define MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP -45 ///< num. PTP unicast masters of the device exceeds max. supp. by driver -#define MBG_ERR_N_GNSS_EXCEEDS_SUPP -46 ///< num. of GNSS systems supp. by device exceeds max. supp. by driver -#define MBG_ERR_N_GPIO_EXCEEDS_SUPP -47 ///< num. of GPIO ports supp. by device exceeds max. supp. by driver -#define MBG_ERR_N_XMR_EXCEEDS_SUPP -48 ///< num. of XMR sources supp. by device exceeds max. supp. by driver - -#define MBG_ERR_UNSPEC -60 ///< unspecified error - -#define MBG_ERR_HDR_CSUM -61 ///< binary protocol header checksum error -#define MBG_ERR_DATA_CSUM -62 ///< binary protocol data checksum error -#define MBG_ERR_RCVD_NACK -63 ///< binary protocol received reply msg with a NACK code -#define MBG_ERR_RCVD_NO_ACK -64 ///< binary protocol received reply msg without expected ACK code -#define MBG_ERR_CONN_TYPE -65 ///< binary protocol no valid/supported connection type specified -#define MBG_ERR_BYTES_WRITTEN -66 ///< binary protocol failed to write all bytes -#define MBG_ERR_AUTH -67 ///< binary protocol failed authentication - -#define MBG_ERR_SOCK_INIT -68 ///< socket interface not initialized, or failed to initialize -#define MBG_ERR_INV_SOCK_FD -69 ///< invalid socket when tried to open network socket -#define MBG_ERR_NOT_A_SOCKET -70 ///< socket descriptor is not a socket -#define MBG_ERR_NBLOCK_WAIT_SLCT -71 ///< select timed when waiting for non-blocking network port to become ready -#define MBG_ERR_NBLOCK_WAIT_WR_FD -72 ///< write fd not set after select when waiting for non-blocking network port to become ready - -#define MBG_ERR_IO -73 ///< generic I/O error -#define MBG_ERR_INV_PARM -74 ///< invalid parameter -#define MBG_ERR_NO_DEV -75 ///< specified device not found -#define MBG_ERR_NOT_FOUND -76 ///< specified item not found - -#define MBG_ERR_OVERFLOW -77 ///< buffer overflow +#define MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP -45 ///< Num. PTP unicast masters of the device exceeds max. supp. by driver. +#define MBG_ERR_N_GNSS_EXCEEDS_SUPP -46 ///< Num. of GNSS systems supp. by device exceeds max. supp. by driver. +#define MBG_ERR_N_GPIO_EXCEEDS_SUPP -47 ///< Num. of GPIO ports supp. by device exceeds max. supp. by driver. +#define MBG_ERR_N_XMR_EXCEEDS_SUPP -48 ///< Num. of XMR sources supp. by device exceeds max. supp. by driver. + +#define MBG_ERR_UNSPEC -60 ///< Unspecified error. + +#define MBG_ERR_HDR_CSUM -61 ///< Binary protocol header checksum error. +#define MBG_ERR_DATA_CSUM -62 ///< Binary protocol data checksum error. +#define MBG_ERR_RCVD_NACK -63 ///< Binary protocol received reply msg with a NACK code. +#define MBG_ERR_RCVD_NO_ACK -64 ///< Binary protocol received reply msg without expected ACK code. //### TODO +#define MBG_ERR_CONN_TYPE -65 ///< Binary protocol no valid/supported connection type specified. +#define MBG_ERR_BYTES_WRITTEN -66 ///< Binary protocol failed to write all bytes. +#define MBG_ERR_AUTH -67 ///< Binary protocol failed authentication. + +#define MBG_ERR_SOCK_INIT -68 ///< Socket interface not initialized, or failed to initialize. +#define MBG_ERR_INV_SOCK_FD -69 ///< Invalid socket when tried to open network socket. +#define MBG_ERR_NOT_A_SOCKET -70 ///< Socket descriptor is not a socket. +#define MBG_ERR_NBLOCK_WAIT_SLCT -71 ///< Select timed out when waiting for non-blocking network port to become ready. +#define MBG_ERR_NBLOCK_WAIT_WR_FD -72 ///< Write fd not set after select when waiting for non-blocking network port to become ready. + +#define MBG_ERR_IO -73 ///< Input/output error. +#define MBG_ERR_INV_PARM -74 ///< Invalid parameter. +#define MBG_ERR_NO_DEV -75 ///< No such device, or attempted an inappropriate function. +#define MBG_ERR_NOT_FOUND -76 ///< Specified item not found. + +#define MBG_ERR_OVERFLOW -77 ///< range or buffer overflow #define MBG_ERR_PIPE -78 ///< pipe error -#define MBG_ERR_INTR -79 ///< interrupted system call -#define MBG_ERR_ACCESS -80 ///< access denied, no permission, eventually distinguish from "Operation not permitted" -#define MBG_ERR_BUSY -81 ///< device busy +#define MBG_ERR_INTR -79 ///< interrupted function call +#define MBG_ERR_ACCESS -80 ///< Access denied, e.g. to an object that is already in use, or in case of insufficient permissions. +#define MBG_ERR_PERM -81 ///< Operation not permitted, e.g. when trying to set the system time without sufficient permissions. +#define MBG_ERR_BUSY -82 ///< Device or resource busy, can't be used +#define MBG_ERR_INV_HANDLE -83 ///< invalid file/device handle specified + +#define MBG_ERR_XBP_CASC_LVL -84 ///< too many XBP cascading levels +#define MBG_ERR_ENCRYPT -85 ///< encryption failed +#define MBG_ERR_DECRYPT -86 ///< decryption failed + +#define MBG_ERR_DISCONN -87 ///< connection closed by remote site / host +#define MBG_ERR_INV_CFG -88 ///< invalid/inconsistent configuration parameters read from device, see also ::MBG_ERR_CFG +#define MBG_ERR_RANGE -89 ///< input parameter was out of range + +#define MBG_ERR_INV_TLV_ANN_BYTES -90 ///< number of announced TLV bytes doesn't match number of transferred bytes +#define MBG_ERR_INV_TLV_SIZE -91 ///< ### TODO +#define MBG_ERR_INV_TLV_UID -92 ///< ### TODO + +#define MBG_ERR_EXIST -93 ///< File exists +#define MBG_ERR_DATA_SIZE -94 ///< the received data size toesn't match the expected data size +#define MBG_ERR_NO_ENTITY -95 ///< no such file or directory +#define MBG_ERR_ALREADY_ALLOC -96 ///< pointer already allocated when trying to allocate memory +#define MBG_ERR_HOST_NOT_FOUND -97 ///< host not found +#define MBG_ERR_CONN_RESET -98 ///< connection reset by peer +#define MBG_ERR_DATA_FMT -99 ///< invalid data format + +#define MBG_ERR_NO_SPACE -100 ///< insufficient disk space left on the device +#define MBG_ERR_NOT_CONFIGURED -101 ///< configuration option is not active/configured +#define MBG_ERR_INV_IDX -102 ///< invalid index value used + +#define MBG_ERR_PARM_FMT -103 ///< parameter string format error +#define MBG_ERR_UNKNOWN -104 ///< Unknown error code from external API. + +#define MBG_ERR_PAM -105 ///< PAM error while authenticating user +#define MBG_ERR_TIMER -106 ///< Timer expired (e.g. stream timeout on USB disconnect) + +#define MBG_ERR_AGAIN -107 ///< Try again (later). For example, a blocking operation + ///< on a non-blocking socket. + +#define MBG_ERR_STR_CHAR -108 ///< Invalid character in string +#define MBG_ERR_STR_LEN -109 ///< Wrong string length +#define MBG_ERR_SN_GCODE_LEN -110 ///< Invalid device group code length +#define MBG_ERR_SN_GCODE_UNKN -111 ///< Unknown device group code +#define MBG_ERR_SN_GCODE_WRONG -112 ///< Wrong device group code in S/N +#define MBG_ERR_SN_LEN -113 ///< Wrong serial number string length +#define MBG_ERR_SN_VRFY -114 ///< Serial number could not be verified + +#define MBG_ERR_RSRC_ITEM -115 ///< Too many resource items +#define MBG_ERR_BUFFER_TOO_SMALL -116 ///< Buffer is too small. + +#define MBG_ERR_OUTDATED -117 + +#define MBG_ERR_STR_SUBSTR -118 ///< Invalid substring in string +#define MBG_ERR_BAD_ADDRESS -119 ///< Bad Address (like POSIX EFAULT) + +#define MBG_ERR_IN_PROGRESS -120 ///< Long lasting operation in progress +#define MBG_ERR_INV_USER -121 ///< Invalid user +#define MBG_ERR_INV_GROUP -122 ///< Invalid group + +// NOTE: New codes have to be appended to this list, and the sequence of codes must not +// be changed. Whenever new codes have been defined, appropriate entries have to be added +// to the ::MBG_ERR_STR_TABLE_ENG table initializer below, and the Windows-specific message +// texts specified in messages.mc/.h from which the resources appended to mbgsvctl.dll +// are generated have to be updated accordingly. /** @} anchor MBG_ERROR_CODES */ @@ -168,62 +419,351 @@ -// Depending on the operating system, the codes above have to be converted before -// they are sent up to user space -#if defined( MBG_TGT_WIN32 ) - #if !defined( STATUS_SUCCESS ) // not in kernel mode - #define STATUS_SUCCESS 0 - #endif +/** + * @brief A basic subset of strings associated with @ref MBG_RETURN_CODES + * + * This initializer provides only the strings for basic error codes + * that are supported on all target systems. + * + * See the @ref MBG_ERR_STR_TABLE_EXT_ENG initializer for error strings + * associated with errors from network and other extended functions. + * + * The generic @ref MBG_ERR_STR_TABLE_ENG initializer should be used + * preferebly since it provides only the basic subset or the full + * set of strings depending on the target system. + * + * @see @ref MBG_ERR_STR_TABLE_ENG + * @see @ref MBG_ERR_STR_TABLE_EXT_ENG + * @see @ref MBG_RETURN_CODES + */ +#define MBG_ERR_STR_TABLE_BASE_ENG \ + { MBG_SUCCESS, "Success" }, \ + { MBG_ERR_STIME, "Invalid date/time for device" }, \ + { MBG_ERR_CFG, "Invalid configuration parameters for device" }, \ + { MBG_ERR_GENERIC, "Generic error" }, \ + { MBG_ERR_TIMEOUT, "Timeout" }, \ + { MBG_ERR_FW_ID, "Invalid firmware ID" }, \ + { MBG_ERR_NBYTES, "Unexpected number of data bytes for this API" }, \ + { MBG_ERR_INV_TIME, "The device has no valid time" }, \ + { MBG_ERR_NO_DATA, "No (more) data to process" }, \ + { MBG_ERR_NOT_READY, "Device not ready" }, \ + { MBG_ERR_INV_TYPE, "Unsupported data type" }, \ + { MBG_ERR_NO_MEM, "Memory allocation error" }, \ + { MBG_ERR_CLAIM_RSRC, "Faild to claim resources" }, \ + { MBG_ERR_DEV_NOT_SUPP, "Device not supported" }, \ + { MBG_ERR_INV_DEV_REQUEST, "Request not supported" }, \ + { MBG_ERR_NOT_SUPP_BY_DEV, "Not supported by device" }, \ + { MBG_ERR_CYCLIC_TIMEOUT, "Cyclic message timeout" }, \ + { MBG_ERR_NOT_SUPP_ON_OS, "Not supported by OS" }, \ + { MBG_ERR_LIB_NOT_COMPATIBLE, "Shared lib not compatible" }, \ + { MBG_ERR_N_COM_EXCEEDS_SUPP, "Num. COM ports exceeds supported" }, \ + { MBG_ERR_N_STR_EXCEEDS_SUPP, "Num. string formats exceeds supported" }, \ + { MBG_ERR_IRQ_UNSAFE, "Unsafe IRQ support" }, \ + { MBG_ERR_N_POUT_EXCEEDS_SUPP, "Num prog. outputs exceeds supported" }, \ + { MBG_ERR_INV_INTNO, "Invalid interrupt number" }, \ + { MBG_ERR_NO_DRIVER, "Driver not found" }, \ + { MBG_ERR_DRV_VERSION, "Driver too old" }, \ + { MBG_ERR_N_UC_MSTR_EXCEEDS_SUPP, "Num. PTP Unicast masters exceeds supported" }, \ + { MBG_ERR_N_GNSS_EXCEEDS_SUPP, "Num. GNSS systems exceeds supported" }, \ + { MBG_ERR_N_GPIO_EXCEEDS_SUPP, "Num. GPIO ports exceeds supported" }, \ + { MBG_ERR_N_XMR_EXCEEDS_SUPP, "Num. XMR sources exceeds supported" }, \ + { MBG_ERR_UNSPEC, "Unspecified error" }, \ + { MBG_ERR_HDR_CSUM, "Header checksum error" }, \ + { MBG_ERR_DATA_CSUM, "Data checksum error" }, \ + { MBG_ERR_RCVD_NACK, "Received NACK message" }, \ + { MBG_ERR_RCVD_NO_ACK, "Didn't receive ACK message" }, \ + { MBG_ERR_CONN_TYPE, "Invalid I/O connection type" }, \ + { MBG_ERR_BYTES_WRITTEN, "Failed to write all bytes" }, \ + { MBG_ERR_IO, "Input/output error" }, \ + { MBG_ERR_INV_PARM, "Invalid parameter passed to function" }, \ + { MBG_ERR_NO_DEV, "No such device, or attempted an inappropriate function." }, \ + { MBG_ERR_NOT_FOUND, "Specified item not found" }, \ + { MBG_ERR_OVERFLOW, "Buffer overflow" }, \ + { MBG_ERR_BUSY, "Device busy" }, \ + { MBG_ERR_INV_HANDLE, "Invalid handle" }, \ + { MBG_ERR_XBP_CASC_LVL, "Too many XBP cascading levels" }, \ + { MBG_ERR_ENCRYPT, "Encryption failed" }, \ + { MBG_ERR_DECRYPT, "Decryption failed" }, \ + { MBG_ERR_DISCONN, "Connection closed by remote site/host" }, \ + { MBG_ERR_INV_CFG, "Invalid/inconsistent configuration read from device" }, \ + { MBG_ERR_RANGE, "Input parameter was out of range" }, \ + { MBG_ERR_INV_TLV_ANN_BYTES, "TLV num of transferred bytes differs from num of announced bytes" }, \ + { MBG_ERR_INV_TLV_SIZE, "MBG_ERR_INV_TLV_SIZE" }, /* ### TODO */ \ + { MBG_ERR_INV_TLV_UID, "MBG_ERR_INV_TLV_UID" }, /* ### TODO */ \ + { MBG_ERR_DATA_SIZE, "Received data size mismatch" }, \ + { MBG_ERR_ALREADY_ALLOC, "Memory already allocated" }, \ + { MBG_ERR_DATA_FMT, "Invalid data format" }, \ + { MBG_ERR_NOT_CONFIGURED, "Configuration is not active and/or configured" }, \ + { MBG_ERR_INV_IDX, "Invalid or unsupported index value used"}, \ + { MBG_ERR_PARM_FMT, "Parameter string format error" }, \ + { MBG_ERR_UNKNOWN, "Unknown error code from external API" }, \ + { MBG_ERR_PAM, "PAM authentication error" }, \ + { MBG_ERR_TIMER, "Timer expired" }, \ + { MBG_ERR_AGAIN, "Try again (later)" }, \ + { MBG_ERR_STR_CHAR, "Invalid character in string" }, \ + { MBG_ERR_STR_LEN, "Wrong string length" }, \ + { MBG_ERR_SN_GCODE_LEN, "Invalid device group code length" }, \ + { MBG_ERR_SN_GCODE_UNKN, "Unknown device group code" }, \ + { MBG_ERR_SN_GCODE_WRONG, "Wrong device group code in S/N" }, \ + { MBG_ERR_SN_VRFY, "Serial number could not be verified" }, \ + { MBG_ERR_RSRC_ITEM, "Too many resource items" }, \ + { MBG_ERR_BUFFER_TOO_SMALL, "Data buffer too small" }, \ + { MBG_ERR_OUTDATED, "Software/Module is too old/outdated. Please update!" }, \ + { MBG_ERR_STR_SUBSTR, "Invalid substring in string" }, \ + { MBG_ERR_IN_PROGRESS, "Long lasting operation in progress" }, \ + { MBG_ERR_INV_USER, "Invalid user" }, \ + { MBG_ERR_INV_GROUP, "Invalid group" } - #define _mbg_err_to_os( _c ) \ - ( ( _c == MBG_SUCCESS ) ? STATUS_SUCCESS : ( abs( _c ) | 0xE0000000 ) ) -#endif +/** + * @brief A subset of extended strings associated with @ref MBG_RETURN_CODES + * + * This initializer provides only the strings associated with extended + * errors from network and other extended functions. + * + * See the @ref MBG_ERR_STR_TABLE_BASE_ENG initializer for error strings + * associated with basic error codes that are supported on all target systems. + * + * The generic @ref MBG_ERR_STR_TABLE_ENG initializer should be used + * preferebly since it provides only the basic subset or the full + * set of strings depending on the target system. + * + * @see @ref MBG_ERR_STR_TABLE_ENG + * @see @ref MBG_ERR_STR_TABLE_BASE_ENG + * @see @ref MBG_RETURN_CODES + */ +#if defined( MBG_TGT_DOS ) + +#define MBG_ERR_STR_TABLE_EXT_ENG \ + { 0, NULL } + +#else + +#define MBG_ERR_STR_TABLE_EXT_ENG \ + { MBG_ERR_COPY_TO_USER, "Error copying to user space" }, \ + { MBG_ERR_COPY_FROM_USER, "Error copying from user space" }, \ + { MBG_ERR_AUTH, "Authentication failed" }, \ + { MBG_ERR_SOCK_INIT, "Failed to initialize socket" }, \ + { MBG_ERR_INV_SOCK_FD, "Invalid socket descriptor" }, \ + { MBG_ERR_NOT_A_SOCKET, "Not a socket descriptor" }, \ + { MBG_ERR_NBLOCK_WAIT_SLCT, "Select timed out waiting for port ready" }, \ + { MBG_ERR_NBLOCK_WAIT_WR_FD, "Write file descriptor not ready after waiting for port ready" }, \ + { MBG_ERR_PIPE, "Pipe error" }, \ + { MBG_ERR_INTR, "Interrupted function call" }, \ + { MBG_ERR_ACCESS, "Access denied" }, \ + { MBG_ERR_PERM, "Operation not permitted, insufficient rights" }, \ + { MBG_ERR_EXIST, "File exists" }, \ + { MBG_ERR_NO_ENTITY, "No such file or directory" }, \ + { MBG_ERR_HOST_NOT_FOUND, "Host not found" }, \ + { MBG_ERR_CONN_RESET, "Connection reset by peer" }, \ + { MBG_ERR_NO_SPACE, "Insufficient disk space" }, \ + { MBG_ERR_PAM, "PAM authentication was not successful" }, \ + { MBG_ERR_TIMER, "Timer expired" }, \ + { MBG_ERR_BAD_ADDRESS, "Bad Address" } -// If no specific conversion has been defined -// then use the original codes. -#if !defined( _mbg_err_to_os ) - #define _mbg_err_to_os( _c ) ( _c ) #endif -/* function prototypes: */ +/** + * @brief Strings associated with @ref MBG_RETURN_CODES + * + * @see @ref MBG_RETURN_CODES + */ +#define MBG_ERR_STR_TABLE_ENG \ +{ \ + MBG_ERR_STR_TABLE_BASE_ENG, \ + MBG_ERR_STR_TABLE_EXT_ENG, \ + { 0, NULL } /* end of table */ \ +} + + + +#if defined( __mbg_inline ) + +static __mbg_inline +/** + * @brief Check if the code returned by a function indicates an error + * + * @param[in] rc One of the @ref MBG_RETURN_CODES + * + * @see ::mbg_rc_is_success + * @see @ref MBG_RETURN_CODES + */ +bool mbg_rc_is_error( int rc ) +{ + // MBG_SUCCESS is 0, and all Meinberg error codes are < 0. + return rc < MBG_SUCCESS; + +} // mbg_rc_is_error + + + +static __mbg_inline +/** + * @brief Check if the code returned by a function indicates success + * + * @param[in] rc One of the @ref MBG_RETURN_CODES + * + * @see ::mbg_rc_is_error + * @see @ref MBG_RETURN_CODES + */ +bool mbg_rc_is_success( int rc ) +{ + // There are functions which don't only return MBG_SUCCESS + // on success but some arbitrary positive number, e.g. the + // number of bytes sent. So success just means "not an error". + return !mbg_rc_is_error( rc ); + +} // mbg_rc_is_success + + + +static __mbg_inline +/** + * @brief Check if a return code indicates success, or the specific code @ref MBG_ERR_PERM + * + * @param[in] rc One of the @ref MBG_RETURN_CODES + * + * @see ::mbg_rc_is_success + * @see @ref MBG_RETURN_CODES + */ +bool mbg_rc_is_success_or_err_perm( int rc ) +{ + return mbg_rc_is_success( rc ) || ( rc == MBG_ERR_PERM ); + +} // mbg_rc_is_success_or_err_perm + + +#else + + #define mbg_rc_is_error( _rc ) ( (_rc) < MBG_SUCCESS ) + #define mbg_rc_is_success( _rc ) ( !mbg_rc_is_error( _rc ) ) + + #define mbg_rc_is_success_or_err_perm( _rc ) ( mbg_rc_is_success( _rc ) || ( (_rc) == MBG_ERR_PERM ) ) -#ifdef __cplusplus -extern "C" { #endif + + +/** + * @brief Predefined exit codes returned by some tools. + */ +enum MBG_EXIT_CODES +{ + MBG_EXIT_CODE_SUCCESS, ///< Requested action completed successfully. + MBG_EXIT_CODE_USAGE, ///< Unable to handle requested action, usage printed. + MBG_EXIT_CODE_NOT_SUPP, ///< Requested action not supported on the running OS. + MBG_EXIT_CODE_FAIL, ///< Action failed for specified device. + MBG_EXIT_CODE_INV_TIME, ///< Device has no valid time to set the system time with. + N_MBG_EXIT_CODES +}; + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ /** - * @brief Translate a Windows non-socket API error code to one of the @ref MBG_ERROR_CODES + * @brief Convert one of the @ref MBG_ERROR_CODES to an OS-specific format + * + * @param[in] err_no One of the @ref MBG_ERROR_CODES. + * + * @see @ref MBG_ERROR_CODES + * + * @return An OS-specific error code + */ + int mbg_errno_to_os( int err_no ) ; + + /** + * @brief Return an error string associated with the @ref MBG_ERROR_CODES + * + * @param[in] mbg_errno One of the @ref MBG_ERROR_CODES + * + * @return A constant string describing the error, or NULL for unknown error codes + */ + const char *mbg_strerror( int mbg_errno ) ; + + /** + * @brief Check if a value is an error code and print an associated error message + * + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES + * @param[in] what A string indicated what failed + * + * @return true if rc represented an error code, and a message has been printed, else false + */ + bool mbg_cond_err_msg( int rc, const char *what ) ; + + /** + * @brief Check if a value is an general or a "not supported" error code and print an associated message + * + * If rc contains an error code then an error message is printed, and true is returned. + * + * If the optional parameter string info2 is not NULL then it should contain + * the name of a feature which has been tested before. In this case, if the error + * code is the specific error ::MBG_ERR_NOT_SUPP_BY_DEV then a "not supported" message + * is printed using info2. * - * @param wsa_err A Windows non-socket API error code as returned by GetLastError() - * @param info An optional informational text string, or NULL + * If info2 is NULL, or the error code is not ::MBG_ERR_NOT_SUPP_BY_DEV then the standard + * error message is printed anyway. + * + * @param[in] rc A positive number including ::MBG_SUCCESS, or one of the @ref MBG_ERROR_CODES + * @param[in] what A string indicated what failed + * @param[in] info An optional informational string telling what is not supported (may be NULL). + * + * @return true if rc represented an error code, and a message has been printed, else false + */ + bool mbg_cond_err_msg_info( int rc, const char *what, const char *info ) ; + + /** + * @brief Translate an error code from the Labwindows/CVI RS-232 library to one of the @ref MBG_ERROR_CODES + * + * @param[in] cvi_rc An error code returned by a CVI RS-232 library function + * @param[in] info An optional informational text string, or NULL * * @return One of the @ref MBG_ERROR_CODES + * + * @see http://zone.ni.com/reference/en-XX/help/370051V-01/cvi/libref/cvirs232_error_conditions/ */ - int mbg_win32_last_err_to_mbg( DWORD wsa_err, const char *info ) ; + int mbg_cvi_rs232_error_to_mbg( int cvi_rc, const char *info ) ; + + /** + * @brief Translate a Windows NTSTATUS code to one of the @ref MBG_ERROR_CODES + * + * @param[in] st One of the NTSTATUS codes defined in ntstatus.h + * @param[in] info An optional informational text string, or NULL + * + * @return One of the @ref MBG_ERROR_CODES + */ + int mbg_win32_ntstatus_to_mbg( NTSTATUS st, const char *info ) ; + + /** + * @brief Translate a Windows non-socket API return code to one of the @ref MBG_RETURN_CODES + * + * @param[in] win32_sys_rc A Windows non-socket API error code as returned by GetLastError(), or ERROR_SUCCESS. + * @param[in] info An optional informational text string, or NULL. + * + * @return One of the @ref MBG_RETURN_CODES + */ + int mbg_win32_sys_err_to_mbg( DWORD win32_sys_rc, const char *info ) ; /** * @brief Translate a Windows socket API error code to one of the @ref MBG_ERROR_CODES * - * @param wsa_err A Windows socket API error code as returned by WSAGetLastError() - * @param info An optional informational text string, or NULL + * @param[in] wsa_err A Windows socket API error code as returned by WSAGetLastError() + * @param[in] info An optional informational text string, or NULL * * @return One of the @ref MBG_ERROR_CODES */ - int mbg_win32_wsa_err_to_mbg( DWORD wsa_err, const char *info ) ; + int mbg_win32_wsa_err_to_mbg( int wsa_err, const char *info ) ; /** * @brief Translate a POSIX errno error code to one of the @ref MBG_ERROR_CODES * - * @param posix_errno A POSIX error code as usually defined in errno.h - * @param info An optional informational text string, or NULL + * @param[in] posix_errno A POSIX error code as usually defined in errno.h + * @param[in] info An optional informational text string, or NULL * * @return One of the @ref MBG_ERROR_CODES */ @@ -239,8 +779,8 @@ extern "C" { * The functions gethostbyname() and gethostbyaddr() are obsolete, * and getaddressinfo() should be used preferably. * - * @param posix_h_errno An error code as usually defined in netdb.h - * @param info An optional informational text string, or NULL + * @param[in] posix_h_errno An error code as usually defined in netdb.h + * @param[in] info An optional informational text string, or NULL * * @return One of the @ref MBG_ERROR_CODES */ @@ -258,7 +798,7 @@ extern "C" { * code from non-socket POSIX-like functions has to be retrieved * by calling GetLastError(). * - * @param info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or NULL * * @return One of the @ref MBG_ERROR_CODES */ @@ -275,7 +815,7 @@ extern "C" { * has to be retrieved by calling WSAGetLastError, whereas the "last error" * code from non-socket POSIX-like functions is stored in errno as usual. * - * @param info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or NULL * * @return One of the @ref MBG_ERROR_CODES */ @@ -293,15 +833,50 @@ extern "C" { * The functions gethostbyname() and gethostbyaddr() are obsolete, * and getaddressinfo() should be used preferably. * - * @param info An optional informational text string, or NULL + * @param[in] info An optional informational text string, or NULL * * @return One of the @ref MBG_ERROR_CODES */ int mbg_get_gethostbyname_error( const char *info ) ; + /** + * @brief Retrieve and convert last zlib internal error code + * + * @param[in] zlib_error zlib internal error code + * @param[in] info An optional informational text string, or NULL + * @param[in] msg An optional zlib specific error msg, or NULL. + * Struct z_stream contains member msg. + * + * @return One of the @ref MBG_ERROR_CODES + */ + int mbg_zlib_error_to_mbg( int zlib_error, const char *info, const char *msg ) ; + /* ----- function prototypes end ----- */ + + +#if _USE_WIN32_PRIVATE_STATUS_CODES + +static __mbg_inline /*HDR*/ +/** + * @brief Convert one of the @ref MBG_RETURN_CODES to an OS-specific code + * + * @param[in] rc One of the @ref MBG_RETURN_CODES. + * + * @see @ref MBG_RETURN_CODES + * + * @return An OS-specific success or error code + */ +int mbg_ret_val_to_os( int rc ) +{ + return mbg_rc_is_success( rc ) ? MBG_SYS_RC_SUCCESS : mbg_errno_to_os( rc ); + +} // mbg_ret_val_to_os + +#endif // _USE_WIN32_PRIVATE_STATUS_CODES + + #ifdef __cplusplus } #endif diff --git a/c/mbglib/include/mbgextio.h b/c/mbglib/include/mbgextio.h deleted file mode 100644 index 11d6ad4..0000000 --- a/c/mbglib/include/mbgextio.h +++ /dev/null @@ -1,265 +0,0 @@ - -/************************************************************************** - * - * $Id: mbgextio.h 1.8.2.14 2012/04/11 15:59:07Z martin TEST $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for mbgextio.c. - * - * ----------------------------------------------------------------------- - * $Log: mbgextio.h $ - * Revision 1.8.2.14 2012/04/11 15:59:07Z martin - * Updated doxygen comments. - * Revision 1.8.2.13 2012/03/13 16:27:45 martin - * Revision 1.8.2.12 2012/03/13 10:48:00Z martin - * Updated function prototypes. - * Revision 1.8.2.11 2012/03/09 10:26:30 martin - * Updated function prototypes. - * Revision 1.8.2.10 2012/03/08 15:52:45Z martin - * Revision 1.8.2.9 2012/03/08 15:48:45 martin - * Revision 1.8.2.8 2012/03/08 15:35:16Z martin - * Support USB I/O. - * Updated function prototypes. - * Revision 1.8.2.7 2012/03/08 13:29:50 martin - * Updated function prototypes. - * Revision 1.8.2.6 2011/11/28 15:46:44 martin - * Updated function prototypes. - * Revision 1.8.2.5 2011/11/25 15:11:21 martin - * Account for renamed event log library symbols. - * Revision 1.8.2.4 2011/11/21 16:34:17 marvin - * new function: support event log - * Revision 1.8.2.3 2011/08/31 09:10:21 marvin - * Updated function prototypes. - * Revision 1.8.2.2 2011/08/23 10:17:08 martin - * Updated function prototypes. - * Revision 1.8.2.1 2011/08/19 13:05:34 martin - * Started to migrate to opaque stuctures. - * Revision 1.8 2011/04/08 11:26:09 martin - * New macros _ttm_time_set_unavail() and _ttm_time_is_avail(). - * Revision 1.7 2009/10/02 14:21:08 martin - * Updated function prototypes. - * Revision 1.6 2009/10/01 11:13:42Z martin - * Updated function prototypes. - * Revision 1.5 2009/03/10 17:03:09Z martin - * Updated function prototypes. - * Revision 1.4 2008/09/04 14:13:19Z martin - * Added macro _mbgextio_xmt_msg(). - * Updated function prototypes. - * Removed obsolete code. - * Revision 1.3 2007/02/27 10:30:06Z martin - * Added some global variables. - * Updated function prototypes. - * Revision 1.2 2006/12/21 10:56:35 martin - * Updated function prototypes. - * Revision 1.1 2006/08/24 12:40:37 martin - * Initial revision. - * - **************************************************************************/ - -#ifndef _MBGEXTIO_H -#define _MBGEXTIO_H - - -/* Other headers to be included */ - -#include <gpsserio.h> -#include <time.h> - -#ifdef _MBGEXTIO - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - - -// The macros below can be used to set a TTM variable to a state -// indicating "time not available", and to check this state. -// This can be used for example to indicate if a capture event -// could have been read from a device, or not. -#define _ttm_time_set_unavail( _t ) do { (_t)->tm.sec = (uint8_t) 0xFF; } while ( 0 ) -#define _ttm_time_is_avail( _t ) ( (uint8_t) (_t)->tm.sec != (uint8_t) 0xFF ) - - -#if _USE_SERIAL_IO - #if !defined( DEFAULT_DEV_NAME ) - #if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_DOS ) - #define DEFAULT_DEV_NAME "COM1" - #elif defined( MBG_TGT_LINUX ) - #define DEFAULT_DEV_NAME "/dev/ttyS0" - #endif - #endif -#endif // _USE_SERIAL_IO - - -#if !_USE_USB_IO - // just to avoid build errors if USB not supported - struct usb_device - { - int dummy; - }; -#endif - - -#if !defined MBGEXTIO_READ_BUFFER_SIZE - #if _USE_SOCKET_IO || _USE_USB_IO - #define MBGEXTIO_READ_BUFFER_SIZE 1000 - #else - #define MBGEXTIO_READ_BUFFER_SIZE 10 - #endif -#endif - - -_ext uint32_t mbg_baud_rates[N_MBG_BAUD_RATES] -#ifdef _DO_INIT - = MBG_BAUD_RATES -#endif -; - -_ext const char *mbg_baud_rate_strs[N_MBG_BAUD_RATES] -#ifdef _DO_INIT - = MBG_BAUD_STRS -#endif -; - -_ext const char *mbg_framing_strs[N_MBG_FRAMINGS] -#ifdef _DO_INIT - = MBG_FRAMING_STRS -#endif -; - - - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - _NO_MBG_API_ATTR MBG_MSG_CTL * _MBG_API mbgextio_open_socket( const char *host, const char *passwd ) ; - _NO_MBG_API_ATTR MBG_MSG_CTL * _MBG_API mbgextio_open_serial( const char *dev, uint32_t baud_rate, const char *framing ) ; - _NO_MBG_API_ATTR MBG_MSG_CTL * _MBG_API mbgextio_open_usb( struct usb_device *usbdev ) ; - _NO_MBG_API_ATTR void _MBG_API mbgextio_close_connection( MBG_MSG_CTL **ppmctl ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_force_connection( const char *dev ) ; - _NO_MBG_API_ATTR MBG_MSG_BUFF * _MBG_API mbgextio_get_rcv_buffer_addr( MBG_MSG_CTL *pmctl ) ; - _NO_MBG_API_ATTR size_t _MBG_API mbgextio_get_rcv_buffer_size( MBG_MSG_CTL *pmctl ) ; - _NO_MBG_API_ATTR MBG_MSG_BUFF * _MBG_API mbgextio_get_xmt_buffer_addr( MBG_MSG_CTL *pmctl ) ; - _NO_MBG_API_ATTR size_t _MBG_API mbgextio_get_xmt_buffer_size( MBG_MSG_CTL *pmctl ) ; - _NO_MBG_API_ATTR void _MBG_API mbgextio_set_char_rcv_timeout( MBG_MSG_CTL *pmctl, ulong new_timeout ) ; - _NO_MBG_API_ATTR ulong _MBG_API mbgextio_get_char_rcv_timeout( const MBG_MSG_CTL *pmctl ) ; - _NO_MBG_API_ATTR void _MBG_API mbgextio_set_msg_rcv_timeout( MBG_MSG_CTL *pmctl, ulong new_timeout ) ; - _NO_MBG_API_ATTR ulong _MBG_API mbgextio_get_msg_rcv_timeout( const MBG_MSG_CTL *pmctl ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_xmt_msg( MBG_MSG_CTL *pmctl, GPS_CMD cmd, const void *p, size_t n_bytes ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_rcv_msg( MBG_MSG_CTL *pmctl, GPS_CMD cmd ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_xmt_cmd( MBG_MSG_CTL *pmctl, GPS_CMD cmd ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_xmt_cmd_us( MBG_MSG_CTL *pmctl, GPS_CMD cmd, uint16_t us ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_req_data( MBG_MSG_CTL *pmctl, GPS_CMD cmd ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_req_data_idx( MBG_MSG_CTL *pmctl, GPS_CMD cmd, uint16_t idx ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_receiver_info( MBG_MSG_CTL *pmctl, RECEIVER_INFO *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_sw_rev( MBG_MSG_CTL *pmctl, SW_REV *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_bvar_stat( MBG_MSG_CTL *pmctl, BVAR_STAT *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_time( MBG_MSG_CTL *pmctl, TTM *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_time( MBG_MSG_CTL *pmctl, const TTM *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_pos_lla( MBG_MSG_CTL *pmctl, LLA lla ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_pos_lla( MBG_MSG_CTL *pmctl, const LLA lla ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_tzdl( MBG_MSG_CTL *pmctl, TZDL *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_tzdl( MBG_MSG_CTL *pmctl, const TZDL *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_port_parm( MBG_MSG_CTL *pmctl, PORT_PARM *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_synth( MBG_MSG_CTL *pmctl, SYNTH *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_synth( MBG_MSG_CTL *pmctl, const SYNTH *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ant_info( MBG_MSG_CTL *pmctl, ANT_INFO *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ucap( MBG_MSG_CTL *pmctl, TTM *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_enable_flags( MBG_MSG_CTL *pmctl, ENABLE_FLAGS *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_enable_flags( MBG_MSG_CTL *pmctl, const ENABLE_FLAGS *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_stat_info( MBG_MSG_CTL *pmctl, STAT_INFO *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ant_cable_len( MBG_MSG_CTL *pmctl, ANT_CABLE_LEN *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_ant_cable_len( MBG_MSG_CTL *pmctl, const ANT_CABLE_LEN *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_irig_tx_info( MBG_MSG_CTL *pmctl, IRIG_INFO *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_irig_tx_settings( MBG_MSG_CTL *pmctl, const IRIG_SETTINGS *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_irig_rx_info( MBG_MSG_CTL *pmctl, IRIG_INFO *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_irig_rx_settings( MBG_MSG_CTL *pmctl, const IRIG_SETTINGS *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_ref_offs( MBG_MSG_CTL *pmctl, MBG_REF_OFFS *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_ref_offs( MBG_MSG_CTL *pmctl, const MBG_REF_OFFS *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_debug_status( MBG_MSG_CTL *pmctl, MBG_DEBUG_STATUS *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_opt_info( MBG_MSG_CTL *pmctl, MBG_OPT_INFO *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_opt_settings( MBG_MSG_CTL *pmctl, const MBG_OPT_SETTINGS *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_str_type_info_idx( MBG_MSG_CTL *pmctl, STR_TYPE_INFO_IDX *p, uint16_t idx ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_all_str_type_info( MBG_MSG_CTL *pmctl, STR_TYPE_INFO_IDX stii[], const RECEIVER_INFO *p_ri ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_port_info_idx( MBG_MSG_CTL *pmctl, PORT_INFO_IDX *p, uint16_t idx ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_all_port_info( MBG_MSG_CTL *pmctl, PORT_INFO_IDX pii[], const RECEIVER_INFO *p_ri ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_port_settings_idx( MBG_MSG_CTL *pmctl, const PORT_SETTINGS *p, uint16_t idx ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_pout_info_idx( MBG_MSG_CTL *pmctl, POUT_INFO_IDX *p, uint16_t idx ) ; - /** - Read all programmable output settings from a non-bus level device. - - The function mbgextio_get_receiver_info() - must have been called before, and the returned ::RECEIVER_INFO - structures must be passed to this function. - - The complementary function mbgextio_save_pout_settings() should - be used to write the modified configuration back to the device. - - @param pmctl Valid handle to a Meinberg device. - @param *pii Pointer to a ::POUT_INFO_IDX structure to be filled up. - @param *p_ri Pointer to a ::RECEIVER_INFO structure. - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbgextio_set_pout_settings_idx() - @see mbgextio_get_receiver_info() -*/ - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_all_pout_info( MBG_MSG_CTL *pmctl, POUT_INFO_IDX *pii, const RECEIVER_INFO *p_ri ) ; - - /** - Write the configuration settings for a single programmable output via serial connection to the board. - - Modifications to the programmable output configuration should be made only - after mbgextio_get_all_pout_info() had been called to read all programmable - output settings and supported configuration parameters. - This function has finally to be called once for every programmable output - the configuration of which has been modified. - - @param pmctl Valid handle to a Meinberg device via serial connection - @param p Pointer to a ::POUT_INFO_IDX structure - @param idx Index of the programmable output to be configured - - @return ::MBG_SUCCESS or error code returned by device I/O control function. - - @see mbgextio_get_all_pout_info() - @see mbgextio_get_receiver_info() -*/ - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_pout_settings_idx( MBG_MSG_CTL *pmctl, const POUT_SETTINGS *p, uint16_t idx ) ; - - _NO_MBG_API_ATTR int _MBG_API mbgextio_clr_ucap_buff( MBG_MSG_CTL *pmctl ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_time_scale_info( MBG_MSG_CTL *pmctl, MBG_TIME_SCALE_INFO *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_set_time_scale_settings( MBG_MSG_CTL *pmctl, const MBG_TIME_SCALE_SETTINGS *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_clr_evt_log( MBG_MSG_CTL *pmctl ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_num_evt_log_entries( MBG_MSG_CTL *pmctl, MBG_NUM_EVT_LOG_ENTRIES *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_first_evt_log_entry( MBG_MSG_CTL *pmctl, MBG_EVT_LOG_ENTRY *p ) ; - _NO_MBG_API_ATTR int _MBG_API mbgextio_get_next_evt_log_entry( MBG_MSG_CTL *pmctl, MBG_EVT_LOG_ENTRY *p ) ; - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - -#define _mbgextio_xmt_msg( _pmctl, _cmd, _s ) \ - mbgextio_xmt_msg( _pmctl, _cmd, _s, sizeof( *(_s) ) ) - -/* End of header body */ - -#undef _ext -#undef _DO_INIT - -#endif /* _MBGEXTIO_H */ diff --git a/c/mbglib/include/mbggeo.h b/c/mbglib/include/mbggeo.h index c3bdb40..9b93617 100644 --- a/c/mbglib/include/mbggeo.h +++ b/c/mbglib/include/mbggeo.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbggeo.h 1.11 2011/06/22 10:18:10Z martin REL_M $ + * $Id: mbggeo.h 1.16 2019/06/17 08:04:51Z thomas-b REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,7 @@ * * Terms used: * - * WGS84 world geodetic system of 1984 + * WGS84 World Geodetic System of 1984 * * XYZ WGS84 earth centered, earth fixed (ECEF) kartesian * coordinates @@ -22,7 +22,18 @@ * * ----------------------------------------------------------------------- * $Log: mbggeo.h $ - * Revision 1.11 2011/06/22 10:18:10Z martin + * Revision 1.16 2019/06/17 08:04:51Z thomas-b + * Renamed structs according to Meinberg naming convention + * Revision 1.15 2019/06/06 12:17:14 thomas-b + * Added several struct names to allow forward declaration + * Revision 1.14 2017/05/10 15:21:40 martin + * Tiny cleanup. + * Revision 1.13 2017/01/27 08:57:58 martin + * Fixed macro syntax. + * Revision 1.12 2016/10/31 16:50:56 martin + * Fixed a typo. + * Updated doxygen comments. + * Revision 1.11 2011/06/22 10:18:10 martin * Cleaned up handling of pragma pack(). * Revision 1.10 2008/09/03 14:54:28 martin * Added macros to swap endianess of structures. @@ -34,7 +45,7 @@ * Revision 1.7 2003/02/14 13:23:04Z martin * Omit inclusion of mystd.h. * Revision 1.6 2003/01/13 15:17:15 martin - * Structures were defined with default alignment which + * Structures were defined with default alignment which * could result in different data sizes on different platforms. * Revision 1.5 2002/12/18 14:46:41Z martin * Removed variable USER_POS meinberg. @@ -69,106 +80,136 @@ #define _USING_BYTE_ALIGNMENT #endif +#ifdef __cplusplus +extern "C" { +#endif + /** - Geographic longitude or latitude in [degrees, minutes, seconds] - longitude East latitude North and positve, South or West angles negative + * @brief Geographic longitude or latitude in [degrees, minutes, seconds] + * + * Longitude East and latitude North are positive angles, South or West + * angles are negative. */ -typedef struct +typedef struct dms_s { - uint16_t prefix; /**< 'N', 'E', 'S' or 'W' */ - uint16_t deg; /**< [0...90 (lat) or 0...180 (lon)] */ - uint16_t min; /**< [0...59] */ - double sec; /**< [0...59.999] */ + uint16_t prefix; ///< 'N', 'E', 'S' or 'W' + uint16_t deg; ///< [0...90 (lat) or 0...180 (lon)] + uint16_t min; ///< [0...59] + double sec; ///< [0...59.99999...] + } DMS; -// The corresponding macro _mbg_swab_dms() is defined in gpsdefs.h. #define _mbg_swab_dms( _p ) \ +do \ { \ _mbg_swab16( &(_p)->prefix ); \ _mbg_swab16( &(_p)->deg ); \ _mbg_swab16( &(_p)->min ); \ _mbg_swab_double( &(_p)->sec ); \ -} +} while ( 0 ) -typedef struct +/** + * @brief A geographic position represented in different formats + */ +typedef struct pos_s { - XYZ xyz; /**< always WGS84 ECEF coordinates */ - LLA lla; /**< depending on the ellipsoid used for reference */ - DMS longitude; /**< longitude in degrees, minutes, seconds */ - DMS latitude; /**< latitude in degrees, minutes, seconds */ - int16_t ellipsoid; /**< ellipsoid used for reference */ + XYZ xyz; ///< Always WGS84 ECEF coordinates + LLA lla; ///< Longitude, latitude and altitude, depending on the ellipsoid used for reference + DMS longitude; ///< Longitude broken down to degrees, minutes, seconds + DMS latitude; ///< Latitude broken down to degrees, minutes, seconds + int16_t ellipsoid; ///< Ellipsoid used for reference, see ::ELLIPSOIDS + } POS; #define _mbg_swab_pos( _p ) \ +do \ { \ _mbg_swab_xyz( (_p)->xyz ); \ _mbg_swab_lla( (_p)->lla ); \ _mbg_swab_dms( &(_p)->longitude ); \ _mbg_swab_dms( &(_p)->latitude ); \ _mbg_swab16( &(_p)->ellipsoid ); \ -} +} while ( 0 ) +/** + * @brief A structure used internally to compute a geographic position + * + * Also contains intermediate results useful for the computation. + */ typedef struct { - CSUM csum; /* checksum of the remaining bytes */ - int16_t valid; /* flag data are valid */ + CSUM csum; ///< Checksum of the remaining bytes + int16_t valid; ///< Indicator if data is valid - char name[40]; - POS pos; /* the position in WGS84 ECEF coords and LLA */ + char name[40]; ///< Informational string + POS pos; ///< The position in WGS84 ECEF coords and ::LLA double det; -/* The components below hold the results of intermediate terms */ -/* computed in complete_user_pos(). */ + // The components below hold the results of intermediate terms + // computed in complete_user_pos(). -/* The sin.., cos.., nt.. and ut.. variables are used to compute the */ -/* enu_dcos[] parameters of a SV structure in xyz_to_ead(). */ + // The sin.., cos.., nt.. and ut.. variables are used to compute the + // enu_dcos[] parameters of a SV structure in xyz_to_ead(). -/* The e_radius.. variables are used to compute the latitude, longitude */ -/* and altitude from ECEF coordinates in lla_to_xyz(). */ + // The e_radius.. variables are used to compute the latitude, longitude + // and altitude from ECEF coordinates in lla_to_xyz(). - double sin_lat; /* sin( latitude ) */ - double cos_lat; /* cos( latitude ) */ - double sin_lon; /* sin( longitude ) */ - double cos_lon; /* cos( longitude ) */ + double sin_lat; ///< sin( latitude ) + double cos_lat; ///< cos( latitude ) + double sin_lon; ///< sin( longitude ) + double cos_lon; ///< cos( longitude ) - double nt1; /* -sin_lat * cos_lon */ - double nt2; /* -sin_lat * sin_lon */ - double utx; /* cos_lat * cos_lon */ - double uty; /* cos_lat * sin_lon */ + double nt1; ///< -sin_lat * cos_lon + double nt2; ///< -sin_lat * sin_lon + double utx; ///< cos_lat * cos_lon + double uty; ///< cos_lat * sin_lon - double e_radius; /* N */ - double e_radius_alt; /* N + h */ + double e_radius; ///< N + double e_radius_alt; ///< N + h } USER_POS; +/** + * @brief Characteristics of a geographic reference ellipsoid + */ typedef struct { - CSUM csum; /* checksum of the remaining bytes */ - int16_t valid; /* flag data are valid */ + CSUM csum; ///< Checksum of the remaining bytes + int16_t valid; ///< Indicator if data is valid char name[40]; - XYZ dxyz; /* offset from the WGS84 ECEF coords */ - double a; /* semi major axis */ - double rcp_f; /* reciproke of flatness */ + XYZ dxyz; ///< Offset from the WGS84 ECEF coords + double a; ///< Semi major axis + double rcp_f; ///< Reciproke of flatness -/* the variables below will be computed in the init_mbggeo() function: */ + // The variables below are computed in the init_mbggeo() function: + + double f; ///< Flatness + double b; ///< Semi minor axis + double sqr_e; ///< Square of numerical eccentricity - double f; /* flatness */ - double b; /* semi minor axis */ - double sqr_e; /* square of numerical eccentricity */ } ELLIPSOID; -enum { WGS84, BESSEL, N_ELLIPSOIDS }; +/** + * @brief An enumeration of known ellipsoids + */ +enum ELLIPSOIDS +{ + WGS84, + BESSEL, + N_ELLIPSOIDS +}; + _ext ELLIPSOID ellipsoid[N_ELLIPSOIDS] #ifdef _DO_INIT @@ -191,15 +232,15 @@ _ext ELLIPSOID ellipsoid[N_ELLIPSOIDS] ; -/* WGS84 constants used */ +// WGS84 constants used -_ext double OMEGADOTe /* earth's rotation rate [rad/sec] */ +_ext double OMEGADOTe // Earth's rotation rate [rad/sec] #ifdef _DO_INIT = 7.2921151467e-5 #endif ; -_ext double mue /* earth's gravitational constant [m^3/sec^2] */ +_ext double mue // Earth's gravitational constant [m^3/sec^2] #ifdef _DO_INIT = 3.986005e14 #endif @@ -249,18 +290,12 @@ _ext double d2r ; -/* variables for simplifying computations */ +// Variables for simplifying computations _ext double gps_two_pi; -_ext double sqrt_mue; /* sqrt( mue ) */ - - +_ext double sqrt_mue; // sqrt( mue ) -/* function prototypes: */ -#ifdef __cplusplus -extern "C" { -#endif /* ----- function prototypes begin ----- */ diff --git a/c/mbglib/include/mbgioctl.h b/c/mbglib/include/mbgioctl.h index d7b8fd6..1fcd7d6 100644 --- a/c/mbglib/include/mbgioctl.h +++ b/c/mbglib/include/mbgioctl.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgioctl.h 1.24.1.15 2012/07/20 11:44:59Z martin TEST $ + * $Id: mbgioctl.h 1.34 2019/04/03 12:28:11Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,30 +10,50 @@ * * ----------------------------------------------------------------------- * $Log: mbgioctl.h $ - * Revision 1.24.1.15 2012/07/20 11:44:59Z martin - * Revision 1.24.1.14 2012/01/25 09:46:31 martin - * Revision 1.24.1.13 2012/01/23 08:43:53 daniel - * test version using alternative way of using generic IO. - * Revision 1.24.1.12 2011/11/25 15:03:23Z martin + * Revision 1.34 2019/04/03 12:28:11Z martin + * Removed obsolete definition PCPS_SPIN_BUFFER. + * Revision 1.33 2019/02/08 16:06:52 martin + * Moved the Windows GUID stuff elsewhere. + * Revision 1.32 2018/11/22 15:01:44 martin + * Refactored structure IOCTL_GENERIC_REQ using fixed size integer + * types only to avoid pointer size problems in a mixed 32/64 bit + * Linux environment. + * Revision 1.31 2018/11/06 17:20:25 martin + * Updated function prototypes and a comment. + * Revision 1.30 2018/08/24 10:03:46Z martin + * Removed code that was commented out. + * Added a comment. + * Revision 1.29 2018/08/08 15:36:50Z martin + * Renamed a local macro for clarity. + * Revision 1.28 2018/07/05 09:02:29Z martin + * Always use DMA-capable buffers as required by Linux kernels 4.9+. + * Moved definition of PCPS_IO_BUFFER and some related + * types to new header file pcpsiobf.h. + * Common, OS-specific definitions for IOCTL return codes. + * Updated function prototypes. + * Revision 1.27 2017/07/05 09:37:18 martin + * Definitions to support GPIO ports and XMR. + * Support new way to check if specific feature supported. + * Moved some IOCTL-related definitions from pcpsdev.h here. + * Added some doxygen comments. + * Revision 1.26 2013/09/26 08:27:04Z martin + * Support GNSS API. + * Revision 1.25 2012/10/02 18:45:55 martin + * There are some g++ versions which fail to compile source code using + * the macros provided by Linux to define IOCTL codes. If only the API + * functions are called by an application then the IOCTL codes aren't + * required anyway, so we just avoid inclusion of mbgioctl.h. + * However, some IOCTL related definitions are required anyway, so + * they have been moved to pcpsdev.h which is always included. * Support on-board event logs. - * Revision 1.24.1.11 2011/11/22 15:47:27 martin * Support debug status. - * Revision 1.24.1.10 2011/07/20 15:49:00 martin * Conditionally use older IOCTL request buffer structures. - * Revision 1.24.1.9 2011/07/19 12:31:59 martin - * Relaxed required priority level for generic read functions. - * Revision 1.24.1.8 2011/07/18 10:18:49 martin - * Revision 1.24.1.7 2011/07/15 14:50:11 martin - * Revision 1.24.1.6 2011/07/14 14:54:01 martin * Modified generic IOCTL handling such that for calls requiring variable sizes * a fixed request block containing input and output buffer pointers and sizes is * passed down to the kernel driver. This simplifies implementation under *BSD * and also works for other target systems. - * Revision 1.24.1.5 2011/07/06 11:19:28 martin * Support reading CORR_INFO, and reading/writing TR_DISTANCE. - * Revision 1.24.1.4 2011/06/29 10:52:00 martin * New code IOCTL_DEV_HAS_PZF. - * Revision 1.24.1.3 2011/06/21 15:03:29 martin * Support PTP unicast configuration. * Changed the names of a few IOCTL codes to follow general naming conventions. * Added definitions to support privilege level requirements for IOCTLs. @@ -41,13 +61,9 @@ * Added definitions to set up a table of all known * IOCTL codes and names. * Use MBG_TGT_KERNEL instead of _KDD_. - * Fixed a typo. - * Revision 1.24.1.2 2011/03/22 11:19:46 martin * Use IOTYPE 'Z' under *BSD since this means passthrough on NetBSD. - * Revision 1.24.1.1 2011/02/15 11:21:21 daniel - * Added ioctls to support PTP unicast configuration * Revision 1.24 2009/12/15 15:34:59Z daniel - * Support reading the raw IRIG data bits for firmware versions + * Support reading the raw IRIG data bits for firmware versions * which support this feature. * Revision 1.23 2009/09/29 15:08:41Z martin * Support retrieving time discipline info. @@ -87,23 +103,23 @@ * Added support for programmable pulse outputs. * Revision 1.12 2005/06/02 10:22:05Z martin * Added IOCTL code IOCTL_GET_SYNTH_STATE. - * Added IOCTL codes IOCTL_DEV_HAS_GENERIC_IO, + * Added IOCTL codes IOCTL_DEV_HAS_GENERIC_IO, * IOCTL_PCPS_GENERIC_IO, and IOCTL_GET_SYNTH_STATE. * Revision 1.11 2005/01/14 10:21:11Z martin * Added IOCTLs which query device features. * Revision 1.10 2004/12/09 11:03:36Z martin * Support configuration of on-board frequency synthesizer. * Revision 1.9 2004/11/09 12:49:41Z martin - * Modifications were required in order to be able to configure IRIG + * Modifications were required in order to be able to configure IRIG * settings of cards which provide both IRIG input and output. - * The existing codes have been renamed with .._RX.. and are used to - * configure the IRIG receiver (input). New codes have been defined + * The existing codes have been renamed with .._RX.. and are used to + * configure the IRIG receiver (input). New codes have been defined * used to configure the IRIG transmitter. * Renamed IOCTL_GET_GPS_STAT to IOCTL_GET_GPS_BVAR_STAT. * Use more specific data types than generic types. * Modified IOCTL codes used for hardware debugging. * Revision 1.8 2004/09/06 15:46:04Z martin - * Changed definition of IOCTL codes to support syntax used + * Changed definition of IOCTL codes to support syntax used * with Linux kernel 2.6.x. * Account for renamed symbols. * Revision 1.7 2004/04/07 10:08:11 martin @@ -137,17 +153,172 @@ /* Other headers to be included */ #include <mbg_tgt.h> +#include <cfg_hlp.h> +#include <mbgerror.h> #include <mbggeo.h> #include <pcpsdev.h> #include <pci_asic.h> +#include <pcpsiobf.h> +#if defined( MBG_TGT_LINUX ) + #include <linux/ioctl.h> +#endif + +#if defined( MBG_TGT_BSD ) + #include <sys/ioccom.h> +#endif + +#if defined( MBG_TGT_WIN32 ) + + #if !defined( MBG_TGT_KERNEL ) + #include <winioctl.h> + #endif + +#endif + + + +/* Start of header body */ + +// We have to use native alignment here! + +#ifdef __cplusplus +extern "C" { +#endif + + +#if defined( MBG_ARCH_X86 ) && defined( DEBUG ) && DEBUG + #define USE_DEBUG_PORT 1 +#else + #define USE_DEBUG_PORT 0 +#endif + + +#if defined( MBG_TGT_POSIX ) && !defined( MBG_TGT_QNX_NTO ) + #define MBG_HAS_POSIX_IOCTL 1 +#endif + + +// A kernel driver's IOCTL handler should return some system-specific +// error code in case of failure. +// We define the most appropriate return codes for specific error +// conditions here, and the IOCTL caller has to map them back to +// one of the @ref MBG_ERROR_CODES. + +#if defined( MBG_TGT_WIN32 ) && defined( MBG_TGT_KERNEL ) + +#if _USE_WIN32_PRIVATE_STATUS_CODES + + // We let the kernel driver's IOCTL handler return private error + // codes in NTSTATUS format, so the DeviceIoControl() function in + // user space fails, and the error code returned by a subsequent + // GetLastError() returns the original custom error code. This + // seems to work well but is an undocumented feature. Also, it + // looks like it's not possible to return a non-error custom + // status code since in case of of success the DeviceIoControl() + // function just returns a BOOL indicating success. + // TODO Test this, and eventually move it to mbgerror.h. + #define _mbg_krn_errno_to_os( _n ) \ + ( ( (_n) == MBG_SUCCESS ) ? STATUS_SUCCESS : \ + ( (NTSTATUS) ( STATUS_SEVERITY_ERROR | STATUS_CUSTOM_FLAG | ( (-(_n)) & 0xFFFF ) ) ) ) + +#else + + // We let the kernel driver's IOCTL handler return system error + // codes in NTSTATUS format, so the DeviceIoControl() function + // in user space fails, and a standard Win32 error code is + // returned by a subsequent GetLastError() call. + // + // ::mbg_errno_to_os in kernel mode uses ::mbg_ioctl_to_ntstatus_table + // to lookup a system NTSTATUS code which is passed up to user space. + // + // The Windows kernel maps that NTSTATUS code to some Win32 error code + // which can be retrieved by calling GetLastError() if DeviceIoControl() + // has failed. + // + // ::mbg_get_last_error in user space calls GetLastError() and + // uses ::win32_error_table to lookup one of the @ref MBG_ERROR_CODES + // associated with the retrieved Win32 error. + // Ideally, this should correspond to the Meinberg error code + // that has been used in kernel mode to lookup the NTSTATUS code. + #define _mbg_krn_errno_to_os( _n ) \ + mbg_errno_to_os( _n ) + +#endif // _USE_WIN32_PRIVATE_STATUS_CODES -#define USE_DEBUG_PORT defined( MBG_ARCH_X86 ) +#endif // defined( MBG_TGT_WIN32 ) && defined( MBG_TGT_KERNEL ) + +#if defined( MBG_TGT_KERNEL ) + +#define IOCTL_RC_SUCCESS MBG_SYS_RC_SUCCESS + #if defined( MBG_TGT_LINUX ) - #include <linux/ioctl.h> + // super user rights required + #define IOCTL_RC_ERR_PERM -EPERM // MBG_ERR_PERM + + #define IOCTL_RC_ERR_UNSUPP_IOCTL -ENODEV // MBG_ERR_INV_DEV_REQUEST ## + + #define IOCTL_RC_ERR_INVAL_PARAM -EINVAL // MBG_ERR_INV_PARM + + #define IOCTL_RC_ERR_NOT_SUPP_BY_DEV -ENOTTY // MBG_ERR_NOT_SUPP_BY_DEV + + #define IOCTL_RC_ERR_NO_MEM -ENOMEM // MBG_ERR_NO_MEM + + #define IOCTL_RC_ERR_BUSY_IRQ_UNSAFE -EBUSY // MBG_ERR_BUSY, MBG_ERR_IRQ_UNSAFE + + #define IOCTL_RC_ERR_DEV_ACCESS -EIO // rc from low level routine + + // Linux-specific codes + #define IOCTL_RC_ERR_COPY_TO_USER -EFAULT // MBG_ERR_COPY_TO_USER + #define IOCTL_RC_ERR_COPY_FROM_USER -EFAULT // MBG_ERR_COPY_FROM_USER + +#elif defined( MBG_TGT_BSD ) // FIXME specific + + // super user rights required + #define IOCTL_RC_ERR_PERM EPERM // MBG_ERR_PERM + + #if defined( ENOIOCTL ) // E.g. FreeBSD, ... + #define IOCTL_RC_ERR_UNSUPP_IOCTL ENOIOCTL // TODO or ENODEV? MBG_ERR_INV_DEV_REQUEST + #else + #define IOCTL_RC_ERR_UNSUPP_IOCTL ENODEV // MBG_ERR_INV_DEV_REQUEST + #endif + + #define IOCTL_RC_ERR_INVAL_PARAM EINVAL // MBG_ERR_INV_PARM + + #define IOCTL_RC_ERR_NOT_SUPP_BY_DEV ENOTTY // MBG_ERR_NOT_SUPP_BY_DEV + + #define IOCTL_RC_ERR_NO_MEM ENOMEM // MBG_ERR_NO_MEM + + #define IOCTL_RC_ERR_BUSY_IRQ_UNSAFE EBUSY // MBG_ERR_BUSY, MBG_ERR_IRQ_UNSAFE + + #define IOCTL_RC_ERR_DEV_ACCESS EIO // TODO or EFAULT? rc from low level routine + +#elif defined( MBG_TGT_WIN32 ) + + #define IOCTL_RC_ERR_PERM _mbg_krn_errno_to_os( MBG_ERR_PERM ) + + #define IOCTL_RC_ERR_UNSUPP_IOCTL _mbg_krn_errno_to_os( MBG_ERR_INV_DEV_REQUEST ) + + #define IOCTL_RC_ERR_INVAL_PARAM _mbg_krn_errno_to_os( MBG_ERR_INV_PARM ) + + #define IOCTL_RC_ERR_NOT_SUPP_BY_DEV _mbg_krn_errno_to_os( MBG_ERR_NOT_SUPP_BY_DEV ) + + #define IOCTL_RC_ERR_NO_MEM _mbg_krn_errno_to_os( MBG_ERR_NO_MEM ) + + #define IOCTL_RC_ERR_BUSY_IRQ_UNSAFE _mbg_krn_errno_to_os( MBG_ERR_IRQ_UNSAFE ) + + #define IOCTL_RC_ERR_DEV_ACCESS _mbg_krn_errno_to_os( rc ) + +#endif + +#endif // defined( MBG_TGT_KERNEL ) + + + +#if defined( MBG_TGT_LINUX ) // a magic number used to generate IOCTL cmd codes #define IOTYPE 'M' @@ -161,8 +332,6 @@ #elif defined( MBG_TGT_BSD ) - #include <sys/ioccom.h> - // Under NetBSD 'Z' marks passthrough IOCTLs, under FreeBSD the code // does not seem to matter, so we use 'Z' anyway. #define IOTYPE 'Z' @@ -179,29 +348,6 @@ #define _MBG_SUPP_VAR_ACC_SIZE 1 #endif - #if !defined( MBG_TGT_KERNEL ) - #include <windows.h> - #include <winioctl.h> - #endif - - #if !defined( MBG_TGT_WIN32_NON_PNP ) - #ifdef _MBGIOCTL - #include <initguid.h> // instance the GUID - #else - #include <guiddef.h> // just define the GUID - #endif - #endif - - #ifdef DEFINE_GUID // don't break compiles of drivers that - // include this header but don't want the - // GUIDs - - // ClassGuid = { 78A1C341-4539-11d3-B88D-00C04FAD5171 } - DEFINE_GUID( GUID_MEINBERG_DEVICE, - 0x78A1C341L, 0x4539, 0x11D3, - 0xB8, 0x8D, 0x00, 0xC0, 0x4F, 0xAD, 0x51, 0x71 ); - #endif - // Device type in the "User Defined" range." #define PCPS_TYPE 40000 @@ -229,18 +375,6 @@ #endif -#ifdef _MBGIOCTL - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -// We must use native alignment here! - // The structure below is used by the IOCTL_PCPS_GENERIC_... calls. @@ -262,16 +396,32 @@ #if USE_IOCTL_GENERIC_REQ -// This does not yet work properly under Linux/Sparc where the kernel may be 64 bit -// while user space is 32 bit, which leads to different sizes for pointers and size_t. - +/** + * @brief A structure used to pass generic IOCTL requests to the kernel driver + * + * In a mixed 32/64 bit environment we may have 32 bit pointers in user space + * but 64 bit pointers in kernel space, so if we defined buffer addresses as + * usual pointers, and buffer sizes as size_t the memory layout of this structure + * would be different in 32 bit and 64 bit builds, so we use only fixed-size types + * to avoid this and make sure the structure has always the same size. + * + * @note Pointers should generally be cast to 'uintptr_t' before being copied + * into the 64 bit address fields. This makes sure 32 bit pointers are expanded + * to 64 bit in an unsigned way, i.e. with the extended bytes always set to 0x00. + * Without this cast a pointer might be extended with 0xFF if the MSB of the + * original 32 bit pointer is set, which would result in an incompatible 64 bit + * address in kernel space. + * In an environment where pointers have 64 bit anyway an 'uintptr_t' cast wouldn't + * be required, but it doesn't hurt, either. + */ typedef struct { - ulong info; - const void *in_p; - size_t in_sz; - void *out_p; - size_t out_sz; + uint64_t in_p; ///< Address of the input buffer. + uint64_t out_p; ///< Address of the output buffer. + uint32_t in_sz; ///< Size of the input buffer. + uint32_t out_sz; ///< Size of the output buffer. + uint32_t info; ///< E.g. cmd code for the device. + uint32_t reserved; ///< Reserved, yet not used. } IOCTL_GENERIC_REQ; @@ -279,18 +429,36 @@ typedef struct #else -// The structure below is used by the IOCTL_PCPS_GENERIC_... calls. +/** + * @brief Control structure used for generic IOCTL requests + * + * Used by the IOCTL_PCPS_GENERIC_... calls. + * + * @note Is slower, but avoids OS-specific problems occurring + * with IOCTL_GENERIC_REQ. + */ typedef struct { uint32_t info; uint32_t data_size_in; uint32_t data_size_out; + } IOCTL_GENERIC_CTL; + +/** + * @brief Data buffer used for generic IOCTL requests + * + * Used by the IOCTL_PCPS_GENERIC_... calls. + * + * @note Is slower, but avoids OS-specific problems occurring + * with IOCTL_GENERIC_REQ. + */ typedef struct { IOCTL_GENERIC_CTL ctl; uint8_t data[1]; + } IOCTL_GENERIC_BUFFER; #define _MBG_IOG( _t, _n, _s ) _MBG_IO( _t, _n ) @@ -299,6 +467,45 @@ typedef struct +/** + * @brief Request buffer used to query a device feature + */ +typedef struct +{ + uint32_t feat_type; ///< See ::DEV_FEAT_TYPES + uint32_t feat_num; ///< Number and range depending on ::IOCTL_DEV_FEAT_REQ::feat_type value + +} IOCTL_DEV_FEAT_REQ; + + + +typedef union +{ + IOCTL_DEV_FEAT_REQ dev_feat_req; + + PCPS_MAPPED_MEM mapped_mem; + + #if USE_IOCTL_GENERIC_REQ + IOCTL_GENERIC_REQ req; + #else + IOCTL_GENERIC_CTL ctl; + #endif + + int i; + +} IOCTL_BUFFER; + + + +/** + * @defgroup group_ioctl_codes IOCTL codes used by Meinberg drivers + * + * @see ::IOCTL_CODES_TABLE + * + * @anchor IOCTL_CODES + * + * @{ */ + // read general driver info, device info, and status port #define IOCTL_GET_PCPS_DRVR_INFO _MBG_IOR( IOTYPE, 0x00, PCPS_DRVR_INFO ) #define IOCTL_GET_PCPS_DEV _MBG_IOR( IOTYPE, 0x01, PCPS_DEV ) @@ -502,6 +709,25 @@ typedef struct #define IOCTL_GET_FIRST_EVT_LOG_ENTRY _MBG_IOR( IOTYPE, 0x93, MBG_EVT_LOG_ENTRY ) #define IOCTL_GET_NEXT_EVT_LOG_ENTRY _MBG_IOR( IOTYPE, 0x94, MBG_EVT_LOG_ENTRY ) +#define IOCTL_DEV_IS_GNSS _MBG_IOR( IOTYPE, 0x95, int ) +#define IOCTL_GET_GNSS_MODE_INFO _MBG_IOR( IOTYPE, 0x96, MBG_GNSS_MODE_INFO ) +#define IOCTL_SET_GNSS_MODE_SETTINGS _MBG_IOW( IOTYPE, 0x97, MBG_GNSS_MODE_SETTINGS ) +#define IOCTL_GET_ALL_GNSS_SAT_INFO _MBG_IOG( IOTYPE, 0x98, IOCTL_GENERIC_REQ ) // variable size + +#define IOCTL_DEV_HAS_GPIO _MBG_IOR( IOTYPE, 0x99, int ) +#define IOCTL_GET_GPIO_CFG_LIMITS _MBG_IOR( IOTYPE, 0x9A, MBG_GPIO_CFG_LIMITS ) +#define IOCTL_GET_ALL_GPIO_INFO _MBG_IOG( IOTYPE, 0x9B, IOCTL_GENERIC_REQ ) // variable size +#define IOCTL_SET_GPIO_SETTINGS_IDX _MBG_IOW( IOTYPE, 0x9C, MBG_GPIO_SETTINGS_IDX ) + +#define IOCTL_DEV_HAS_XMR _MBG_IOR( IOTYPE, 0x9D, int ) +#define IOCTL_GET_XMR_INSTANCES _MBG_IOR( IOTYPE, 0x9E, XMULTI_REF_INSTANCES ) +#define IOCTL_GET_ALL_XMR_INFO _MBG_IOG( IOTYPE, 0x9F, IOCTL_GENERIC_REQ ) // variable size +#define IOCTL_SET_XMR_SETTINGS_IDX _MBG_IOW( IOTYPE, 0xA0, XMULTI_REF_SETTINGS_IDX ) +#define IOCTL_GET_ALL_XMR_STATUS _MBG_IOG( IOTYPE, 0xA1, IOCTL_GENERIC_REQ ) // variable size +#define IOCTL_GET_XMR_HOLDOVER_STATUS _MBG_IOR( IOTYPE, 0xA2, XMR_HOLDOVER_STATUS ) + +#define IOCTL_GET_ALL_GPIO_STATUS _MBG_IOG( IOTYPE, 0xA3, IOCTL_GENERIC_REQ ) // variable size +#define IOCTL_CHK_DEV_FEAT _MBG_IOW( IOTYPE, 0xA4, IOCTL_DEV_FEAT_REQ ) // The codes below are subject to changes without notice. They may be supported // by some kernel drivers, but usage is restricted to Meinberg software development. @@ -512,162 +738,184 @@ typedef struct #define IOCTL_MBG_DBG_CLR_BIT _MBG_IOW( IOTYPE, 0xF3, uint8_t ) #define IOCTL_MBG_DBG_CLR_ALL _MBG_IO( IOTYPE, 0xF4 ) +/** @} defgroup group_ioctl_codes */ + /** * @brief An initializer for a table of IOCTL codes and associated names. * - * This can e.g. be assigned to an array of MBG_CODE_NAME_TABLE_ENTRY elements + * This can e.g. initialize an array of ::MBG_CODE_NAME_TABLE_ENTRY elements * and may be helpful when debugging. + * + * @see @ref IOCTL_CODES */ -#define MBG_IOCTL_CODE_TABLE \ -{ \ - { IOCTL_GET_PCPS_DRVR_INFO, "IOCTL_GET_PCPS_DRVR_INFO" }, \ - { IOCTL_GET_PCPS_DEV, "IOCTL_GET_PCPS_DEV" }, \ - { IOCTL_GET_PCPS_STATUS_PORT, "IOCTL_GET_PCPS_STATUS_PORT" }, \ - { IOCTL_PCPS_GENERIC_READ, "IOCTL_PCPS_GENERIC_READ" }, \ - { IOCTL_PCPS_GENERIC_WRITE, "IOCTL_PCPS_GENERIC_WRITE" }, \ - { IOCTL_PCPS_GENERIC_READ_GPS, "IOCTL_PCPS_GENERIC_READ_GPS" }, \ - { IOCTL_PCPS_GENERIC_WRITE_GPS, "IOCTL_PCPS_GENERIC_WRITE_GPS" }, \ - { IOCTL_GET_PCPS_TIME, "IOCTL_GET_PCPS_TIME" }, \ - { IOCTL_SET_PCPS_TIME, "IOCTL_SET_PCPS_TIME" }, \ - { IOCTL_GET_PCPS_SYNC_TIME, "IOCTL_GET_PCPS_SYNC_TIME" }, \ - { IOCTL_GET_PCPS_TIME_SEC_CHANGE, "IOCTL_GET_PCPS_TIME_SEC_CHANGE" }, \ - { IOCTL_GET_PCPS_HR_TIME, "IOCTL_GET_PCPS_HR_TIME" }, \ - { IOCTL_SET_PCPS_EVENT_TIME, "IOCTL_SET_PCPS_EVENT_TIME" }, \ - { IOCTL_GET_PCPS_SERIAL, "IOCTL_GET_PCPS_SERIAL" }, \ - { IOCTL_SET_PCPS_SERIAL, "IOCTL_SET_PCPS_SERIAL" }, \ - { IOCTL_GET_PCPS_TZCODE, "IOCTL_GET_PCPS_TZCODE" }, \ - { IOCTL_SET_PCPS_TZCODE, "IOCTL_SET_PCPS_TZCODE" }, \ - { IOCTL_GET_PCPS_TZDL, "IOCTL_GET_PCPS_TZDL" }, \ - { IOCTL_SET_PCPS_TZDL, "IOCTL_SET_PCPS_TZDL" }, \ - { IOCTL_GET_REF_OFFS, "IOCTL_GET_REF_OFFS" }, \ - { IOCTL_SET_REF_OFFS, "IOCTL_SET_REF_OFFS" }, \ - { IOCTL_GET_MBG_OPT_INFO, "IOCTL_GET_MBG_OPT_INFO" }, \ - { IOCTL_SET_MBG_OPT_SETTINGS, "IOCTL_SET_MBG_OPT_SETTINGS" }, \ - { IOCTL_GET_PCPS_IRIG_RX_INFO, "IOCTL_GET_PCPS_IRIG_RX_INFO" }, \ - { IOCTL_SET_PCPS_IRIG_RX_SETTINGS, "IOCTL_SET_PCPS_IRIG_RX_SETTINGS" }, \ - { IOCTL_PCPS_CLR_UCAP_BUFF, "IOCTL_PCPS_CLR_UCAP_BUFF" }, \ - { IOCTL_GET_PCPS_UCAP_ENTRIES, "IOCTL_GET_PCPS_UCAP_ENTRIES" }, \ - { IOCTL_GET_PCPS_UCAP_EVENT, "IOCTL_GET_PCPS_UCAP_EVENT" }, \ - { IOCTL_GET_GPS_TZDL, "IOCTL_GET_GPS_TZDL" }, \ - { IOCTL_SET_GPS_TZDL, "IOCTL_SET_GPS_TZDL" }, \ - { IOCTL_GET_GPS_SW_REV, "IOCTL_GET_GPS_SW_REV" }, \ - { IOCTL_GET_GPS_BVAR_STAT, "IOCTL_GET_GPS_BVAR_STAT" }, \ - { IOCTL_GET_GPS_TIME, "IOCTL_GET_GPS_TIME" }, \ - { IOCTL_SET_GPS_TIME, "IOCTL_SET_GPS_TIME" }, \ - { IOCTL_GET_GPS_PORT_PARM, "IOCTL_GET_GPS_PORT_PARM" }, \ - { IOCTL_SET_GPS_PORT_PARM, "IOCTL_SET_GPS_PORT_PARM" }, \ - { IOCTL_GET_GPS_ANT_INFO, "IOCTL_GET_GPS_ANT_INFO" }, \ - { IOCTL_GET_GPS_UCAP, "IOCTL_GET_GPS_UCAP" }, \ - { IOCTL_GET_GPS_ENABLE_FLAGS, "IOCTL_GET_GPS_ENABLE_FLAGS" }, \ - { IOCTL_SET_GPS_ENABLE_FLAGS, "IOCTL_SET_GPS_ENABLE_FLAGS" }, \ - { IOCTL_GET_GPS_STAT_INFO, "IOCTL_GET_GPS_STAT_INFO" }, \ - { IOCTL_SET_GPS_CMD, "IOCTL_SET_GPS_CMD" }, \ - { IOCTL_GET_GPS_IDENT, "IOCTL_GET_GPS_IDENT" }, \ - { IOCTL_GET_GPS_POS, "IOCTL_GET_GPS_POS" }, \ - { IOCTL_SET_GPS_POS_XYZ, "IOCTL_SET_GPS_POS_XYZ" }, \ - { IOCTL_SET_GPS_POS_LLA, "IOCTL_SET_GPS_POS_LLA" }, \ - { IOCTL_GET_GPS_ANT_CABLE_LEN, "IOCTL_GET_GPS_ANT_CABLE_LEN" }, \ - { IOCTL_SET_GPS_ANT_CABLE_LEN, "IOCTL_SET_GPS_ANT_CABLE_LEN" }, \ - { IOCTL_GET_GPS_RECEIVER_INFO, "IOCTL_GET_GPS_RECEIVER_INFO" }, \ - { IOCTL_GET_GPS_ALL_STR_TYPE_INFO, "IOCTL_GET_GPS_ALL_STR_TYPE_INFO" }, \ - { IOCTL_GET_GPS_ALL_PORT_INFO, "IOCTL_GET_GPS_ALL_PORT_INFO" }, \ - { IOCTL_SET_GPS_PORT_SETTINGS_IDX, "IOCTL_SET_GPS_PORT_SETTINGS_IDX" }, \ - { IOCTL_GET_PCI_ASIC_VERSION, "IOCTL_GET_PCI_ASIC_VERSION" }, \ - { IOCTL_GET_PCPS_TIME_CYCLES, "IOCTL_GET_PCPS_TIME_CYCLES" }, \ - { IOCTL_GET_PCPS_HR_TIME_CYCLES, "IOCTL_GET_PCPS_HR_TIME_CYCLES" }, \ - { IOCTL_GET_PCPS_IRIG_TX_INFO, "IOCTL_GET_PCPS_IRIG_TX_INFO" }, \ - { IOCTL_SET_PCPS_IRIG_TX_SETTINGS, "IOCTL_SET_PCPS_IRIG_TX_SETTINGS" }, \ - { IOCTL_GET_SYNTH, "IOCTL_GET_SYNTH" }, \ - { IOCTL_SET_SYNTH, "IOCTL_SET_SYNTH" }, \ - { IOCTL_DEV_IS_GPS, "IOCTL_DEV_IS_GPS" }, \ - { IOCTL_DEV_IS_DCF, "IOCTL_DEV_IS_DCF" }, \ - { IOCTL_DEV_IS_IRIG_RX, "IOCTL_DEV_IS_IRIG_RX" }, \ - { IOCTL_DEV_HAS_HR_TIME, "IOCTL_DEV_HAS_HR_TIME" }, \ - { IOCTL_DEV_HAS_CAB_LEN, "IOCTL_DEV_HAS_CAB_LEN" }, \ - { IOCTL_DEV_HAS_TZDL, "IOCTL_DEV_HAS_TZDL" }, \ - { IOCTL_DEV_HAS_PCPS_TZDL, "IOCTL_DEV_HAS_PCPS_TZDL" }, \ - { IOCTL_DEV_HAS_TZCODE, "IOCTL_DEV_HAS_TZCODE" }, \ - { IOCTL_DEV_HAS_TZ, "IOCTL_DEV_HAS_TZ" }, \ - { IOCTL_DEV_HAS_EVENT_TIME, "IOCTL_DEV_HAS_EVENT_TIME" }, \ - { IOCTL_DEV_HAS_RECEIVER_INFO, "IOCTL_DEV_HAS_RECEIVER_INFO" }, \ - { IOCTL_DEV_CAN_CLR_UCAP_BUFF, "IOCTL_DEV_CAN_CLR_UCAP_BUFF" }, \ - { IOCTL_DEV_HAS_UCAP, "IOCTL_DEV_HAS_UCAP" }, \ - { IOCTL_DEV_HAS_IRIG_TX, "IOCTL_DEV_HAS_IRIG_TX" }, \ - { IOCTL_DEV_HAS_SERIAL_HS, "IOCTL_DEV_HAS_SERIAL_HS" }, \ - { IOCTL_DEV_HAS_SIGNAL, "IOCTL_DEV_HAS_SIGNAL" }, \ - { IOCTL_DEV_HAS_MOD, "IOCTL_DEV_HAS_MOD" }, \ - { IOCTL_DEV_HAS_IRIG, "IOCTL_DEV_HAS_IRIG" }, \ - { IOCTL_DEV_HAS_REF_OFFS, "IOCTL_DEV_HAS_REF_OFFS" }, \ - { IOCTL_DEV_HAS_OPT_FLAGS, "IOCTL_DEV_HAS_OPT_FLAGS" }, \ - { IOCTL_DEV_HAS_GPS_DATA, "IOCTL_DEV_HAS_GPS_DATA" }, \ - { IOCTL_DEV_HAS_SYNTH, "IOCTL_DEV_HAS_SYNTH" }, \ - { IOCTL_DEV_HAS_GENERIC_IO, "IOCTL_DEV_HAS_GENERIC_IO" }, \ - { IOCTL_PCPS_GENERIC_IO, "IOCTL_PCPS_GENERIC_IO" }, \ - { IOCTL_GET_SYNTH_STATE, "IOCTL_GET_SYNTH_STATE" }, \ - { IOCTL_GET_GPS_ALL_POUT_INFO, "IOCTL_GET_GPS_ALL_POUT_INFO" }, \ - { IOCTL_SET_GPS_POUT_SETTINGS_IDX, "IOCTL_SET_GPS_POUT_SETTINGS_IDX" }, \ - { IOCTL_GET_MAPPED_MEM_ADDR, "IOCTL_GET_MAPPED_MEM_ADDR" }, \ - { IOCTL_UNMAP_MAPPED_MEM, "IOCTL_UNMAP_MAPPED_MEM" }, \ - { IOCTL_GET_PCI_ASIC_FEATURES, "IOCTL_GET_PCI_ASIC_FEATURES" }, \ - { IOCTL_DEV_HAS_PCI_ASIC_FEATURES, "IOCTL_DEV_HAS_PCI_ASIC_FEATURES" }, \ - { IOCTL_DEV_HAS_PCI_ASIC_VERSION, "IOCTL_DEV_HAS_PCI_ASIC_VERSION" }, \ - { IOCTL_DEV_IS_MSF, "IOCTL_DEV_IS_MSF" }, \ - { IOCTL_DEV_IS_LWR, "IOCTL_DEV_IS_LWR" }, \ - { IOCTL_DEV_IS_WWVB, "IOCTL_DEV_IS_WWVB" }, \ - { IOCTL_GET_IRQ_STAT_INFO, "IOCTL_GET_IRQ_STAT_INFO" }, \ - { IOCTL_GET_CYCLES_FREQUENCY, "IOCTL_GET_CYCLES_FREQUENCY" }, \ - { IOCTL_DEV_HAS_FAST_HR_TIMESTAMP, "IOCTL_DEV_HAS_FAST_HR_TIMESTAMP" }, \ - { IOCTL_GET_FAST_HR_TIMESTAMP_CYCLES, "IOCTL_GET_FAST_HR_TIMESTAMP_CYCLES" }, \ - { IOCTL_GET_FAST_HR_TIMESTAMP, "IOCTL_GET_FAST_HR_TIMESTAMP" }, \ - { IOCTL_DEV_HAS_GPS_TIME_SCALE, "IOCTL_DEV_HAS_GPS_TIME_SCALE" }, \ - { IOCTL_GET_GPS_TIME_SCALE_INFO, "IOCTL_GET_GPS_TIME_SCALE_INFO" }, \ - { IOCTL_SET_GPS_TIME_SCALE_SETTINGS, "IOCTL_SET_GPS_TIME_SCALE_SETTINGS" }, \ - { IOCTL_DEV_HAS_GPS_UTC_PARM, "IOCTL_DEV_HAS_GPS_UTC_PARM" }, \ - { IOCTL_GET_GPS_UTC_PARM, "IOCTL_GET_GPS_UTC_PARM" }, \ - { IOCTL_SET_GPS_UTC_PARM, "IOCTL_SET_GPS_UTC_PARM" }, \ - { IOCTL_DEV_HAS_IRIG_CTRL_BITS, "IOCTL_DEV_HAS_IRIG_CTRL_BITS" }, \ - { IOCTL_GET_IRIG_CTRL_BITS, "IOCTL_GET_IRIG_CTRL_BITS" }, \ - { IOCTL_DEV_HAS_LAN_INTF, "IOCTL_DEV_HAS_LAN_INTF" }, \ - { IOCTL_GET_LAN_IF_INFO, "IOCTL_GET_LAN_IF_INFO" }, \ - { IOCTL_GET_IP4_STATE, "IOCTL_GET_IP4_STATE" }, \ - { IOCTL_GET_IP4_SETTINGS, "IOCTL_GET_IP4_SETTINGS" }, \ - { IOCTL_SET_IP4_SETTINGS, "IOCTL_SET_IP4_SETTINGS" }, \ - { IOCTL_DEV_IS_PTP, "IOCTL_DEV_IS_PTP" }, \ - { IOCTL_DEV_HAS_PTP, "IOCTL_DEV_HAS_PTP" }, \ - { IOCTL_GET_PTP_STATE, "IOCTL_GET_PTP_STATE" }, \ - { IOCTL_GET_PTP_CFG_INFO, "IOCTL_GET_PTP_CFG_INFO" }, \ - { IOCTL_SET_PTP_CFG_SETTINGS, "IOCTL_SET_PTP_CFG_SETTINGS" }, \ - { IOCTL_DEV_HAS_IRIG_TIME, "IOCTL_DEV_HAS_IRIG_TIME" }, \ - { IOCTL_GET_IRIG_TIME, "IOCTL_GET_IRIG_TIME" }, \ - { IOCTL_GET_TIME_INFO_HRT, "IOCTL_GET_TIME_INFO_HRT" }, \ - { IOCTL_GET_TIME_INFO_TSTAMP, "IOCTL_GET_TIME_INFO_TSTAMP" }, \ - { IOCTL_DEV_HAS_RAW_IRIG_DATA, "IOCTL_DEV_HAS_RAW_IRIG_DATA" }, \ - { IOCTL_GET_RAW_IRIG_DATA, "IOCTL_GET_RAW_IRIG_DATA" }, \ - { IOCTL_DEV_HAS_PTP_UNICAST, "IOCTL_DEV_HAS_PTP_UNICAST" }, \ - { IOCTL_PTP_UC_MASTER_CFG_LIMITS, "IOCTL_PTP_UC_MASTER_CFG_LIMITS" }, \ - { IOCTL_GET_ALL_PTP_UC_MASTER_INFO, "IOCTL_GET_ALL_PTP_UC_MASTER_INFO" }, \ - { IOCTL_SET_PTP_UC_MASTER_SETTINGS_IDX, "IOCTL_SET_PTP_UC_MASTER_SETTINGS_IDX" }, \ - { IOCTL_DEV_HAS_PZF, "IOCTL_DEV_HAS_PZF" }, \ - { IOCTL_DEV_HAS_CORR_INFO, "IOCTL_DEV_HAS_CORR_INFO" }, \ - { IOCTL_DEV_HAS_TR_DISTANCE, "IOCTL_DEV_HAS_TR_DISTANCE" }, \ - { IOCTL_GET_CORR_INFO, "IOCTL_GET_CORR_INFO" }, \ - { IOCTL_GET_TR_DISTANCE, "IOCTL_GET_TR_DISTANCE" }, \ - { IOCTL_SET_TR_DISTANCE, "IOCTL_SET_TR_DISTANCE" }, \ - { IOCTL_DEV_HAS_DEBUG_STATUS, "IOCTL_DEV_HAS_DEBUG_STATUS" }, \ - { IOCTL_GET_DEBUG_STATUS, "IOCTL_GET_DEBUG_STATUS" }, \ - { IOCTL_DEV_HAS_EVT_LOG, "IOCTL_DEV_HAS_EVT_LOG" }, \ - { IOCTL_CLR_EVT_LOG, "IOCTL_CLR_EVT_LOG" }, \ - { IOCTL_GET_NUM_EVT_LOG_ENTRIES, "IOCTL_GET_NUM_EVT_LOG_ENTRIES" }, \ - { IOCTL_GET_FIRST_EVT_LOG_ENTRY, "IOCTL_GET_FIRST_EVT_LOG_ENTRY" }, \ - { IOCTL_GET_NEXT_EVT_LOG_ENTRY, "IOCTL_GET_NEXT_EVT_LOG_ENTRY" }, \ - \ - { IOCTL_MBG_DBG_GET_PORT_ADDR, "IOCTL_MBG_DBG_GET_PORT_ADDR" }, \ - { IOCTL_MBG_DBG_SET_PORT_ADDR, "IOCTL_MBG_DBG_SET_PORT_ADDR" }, \ - { IOCTL_MBG_DBG_SET_BIT, "IOCTL_MBG_DBG_SET_BIT" }, \ - { IOCTL_MBG_DBG_CLR_BIT, "IOCTL_MBG_DBG_CLR_BIT" }, \ - { 0, NULL } \ +#define IOCTL_CODES_TABLE \ +{ \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_DRVR_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_DEV ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_STATUS_PORT ), \ + _mbg_cn_table_entry( IOCTL_PCPS_GENERIC_READ ), \ + _mbg_cn_table_entry( IOCTL_PCPS_GENERIC_WRITE ), \ + _mbg_cn_table_entry( IOCTL_PCPS_GENERIC_READ_GPS ), \ + _mbg_cn_table_entry( IOCTL_PCPS_GENERIC_WRITE_GPS ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_TIME ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_SYNC_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_TIME_SEC_CHANGE ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_HR_TIME ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_EVENT_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_SERIAL ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_SERIAL ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_TZCODE ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_TZCODE ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_GET_REF_OFFS ), \ + _mbg_cn_table_entry( IOCTL_SET_REF_OFFS ), \ + _mbg_cn_table_entry( IOCTL_GET_MBG_OPT_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_MBG_OPT_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_IRIG_RX_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_IRIG_RX_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_PCPS_CLR_UCAP_BUFF ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_UCAP_ENTRIES ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_UCAP_EVENT ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_SW_REV ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_BVAR_STAT ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_TIME ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_PORT_PARM ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_PORT_PARM ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ANT_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_UCAP ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ENABLE_FLAGS ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_ENABLE_FLAGS ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_STAT_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_CMD ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_IDENT ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_POS ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_POS_XYZ ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_POS_LLA ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ANT_CABLE_LEN ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_ANT_CABLE_LEN ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_RECEIVER_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ALL_STR_TYPE_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ALL_PORT_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_PORT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( IOCTL_GET_PCI_ASIC_VERSION ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_TIME_CYCLES ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_HR_TIME_CYCLES ), \ + _mbg_cn_table_entry( IOCTL_GET_PCPS_IRIG_TX_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_PCPS_IRIG_TX_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_GET_SYNTH ), \ + _mbg_cn_table_entry( IOCTL_SET_SYNTH ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_GPS ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_DCF ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_IRIG_RX ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_HR_TIME ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_CAB_LEN ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PCPS_TZDL ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_TZCODE ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_TZ ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_EVENT_TIME ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_RECEIVER_INFO ), \ + _mbg_cn_table_entry( IOCTL_DEV_CAN_CLR_UCAP_BUFF ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_UCAP ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_IRIG_TX ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_SERIAL_HS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_SIGNAL ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_MOD ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_IRIG ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_REF_OFFS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_OPT_FLAGS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_GPS_DATA ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_SYNTH ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_GENERIC_IO ), \ + _mbg_cn_table_entry( IOCTL_PCPS_GENERIC_IO ), \ + _mbg_cn_table_entry( IOCTL_GET_SYNTH_STATE ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_ALL_POUT_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_POUT_SETTINGS_IDX ), \ + _mbg_cn_table_entry( IOCTL_GET_MAPPED_MEM_ADDR ), \ + _mbg_cn_table_entry( IOCTL_UNMAP_MAPPED_MEM ), \ + _mbg_cn_table_entry( IOCTL_GET_PCI_ASIC_FEATURES ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PCI_ASIC_FEATURES ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PCI_ASIC_VERSION ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_MSF ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_LWR ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_WWVB ), \ + _mbg_cn_table_entry( IOCTL_GET_IRQ_STAT_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_CYCLES_FREQUENCY ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_FAST_HR_TIMESTAMP ), \ + _mbg_cn_table_entry( IOCTL_GET_FAST_HR_TIMESTAMP_CYCLES ), \ + _mbg_cn_table_entry( IOCTL_GET_FAST_HR_TIMESTAMP ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_GPS_TIME_SCALE ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_TIME_SCALE_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_TIME_SCALE_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_GPS_UTC_PARM ), \ + _mbg_cn_table_entry( IOCTL_GET_GPS_UTC_PARM ), \ + _mbg_cn_table_entry( IOCTL_SET_GPS_UTC_PARM ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_IRIG_CTRL_BITS ), \ + _mbg_cn_table_entry( IOCTL_GET_IRIG_CTRL_BITS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_LAN_INTF ), \ + _mbg_cn_table_entry( IOCTL_GET_LAN_IF_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_IP4_STATE ), \ + _mbg_cn_table_entry( IOCTL_GET_IP4_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_SET_IP4_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_PTP ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PTP ), \ + _mbg_cn_table_entry( IOCTL_GET_PTP_STATE ), \ + _mbg_cn_table_entry( IOCTL_GET_PTP_CFG_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_PTP_CFG_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_IRIG_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_IRIG_TIME ), \ + _mbg_cn_table_entry( IOCTL_GET_TIME_INFO_HRT ), \ + _mbg_cn_table_entry( IOCTL_GET_TIME_INFO_TSTAMP ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_RAW_IRIG_DATA ), \ + _mbg_cn_table_entry( IOCTL_GET_RAW_IRIG_DATA ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PTP_UNICAST ), \ + _mbg_cn_table_entry( IOCTL_PTP_UC_MASTER_CFG_LIMITS ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_PTP_UC_MASTER_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_PTP_UC_MASTER_SETTINGS_IDX ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_PZF ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_CORR_INFO ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_TR_DISTANCE ), \ + _mbg_cn_table_entry( IOCTL_GET_CORR_INFO ), \ + _mbg_cn_table_entry( IOCTL_GET_TR_DISTANCE ), \ + _mbg_cn_table_entry( IOCTL_SET_TR_DISTANCE ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_DEBUG_STATUS ), \ + _mbg_cn_table_entry( IOCTL_GET_DEBUG_STATUS ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_EVT_LOG ), \ + _mbg_cn_table_entry( IOCTL_CLR_EVT_LOG ), \ + _mbg_cn_table_entry( IOCTL_GET_NUM_EVT_LOG_ENTRIES ), \ + _mbg_cn_table_entry( IOCTL_GET_FIRST_EVT_LOG_ENTRY ), \ + _mbg_cn_table_entry( IOCTL_GET_NEXT_EVT_LOG_ENTRY ), \ + _mbg_cn_table_entry( IOCTL_DEV_IS_GNSS ), \ + _mbg_cn_table_entry( IOCTL_GET_GNSS_MODE_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GNSS_MODE_SETTINGS ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_GNSS_SAT_INFO ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_GPIO ), \ + _mbg_cn_table_entry( IOCTL_GET_GPIO_CFG_LIMITS ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_GPIO_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_GPIO_SETTINGS_IDX ), \ + _mbg_cn_table_entry( IOCTL_DEV_HAS_XMR ), \ + _mbg_cn_table_entry( IOCTL_GET_XMR_INSTANCES ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_XMR_INFO ), \ + _mbg_cn_table_entry( IOCTL_SET_XMR_SETTINGS_IDX ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_XMR_STATUS ), \ + _mbg_cn_table_entry( IOCTL_GET_XMR_HOLDOVER_STATUS ), \ + _mbg_cn_table_entry( IOCTL_GET_ALL_GPIO_STATUS ), \ + _mbg_cn_table_entry( IOCTL_CHK_DEV_FEAT ), \ + \ + _mbg_cn_table_entry( IOCTL_MBG_DBG_GET_PORT_ADDR ), \ + _mbg_cn_table_entry( IOCTL_MBG_DBG_SET_PORT_ADDR ), \ + _mbg_cn_table_entry( IOCTL_MBG_DBG_SET_BIT ), \ + _mbg_cn_table_entry( IOCTL_MBG_DBG_CLR_BIT ), \ + _mbg_cn_table_entry( IOCTL_MBG_DBG_CLR_ALL ), \ + \ + _mbg_cn_table_end() \ } @@ -771,6 +1019,9 @@ int ioctl_get_required_privilege( ulong ioctl_code ) case IOCTL_GET_NUM_EVT_LOG_ENTRIES: case IOCTL_GET_FIRST_EVT_LOG_ENTRY: case IOCTL_GET_NEXT_EVT_LOG_ENTRY: + #if _MBG_SUPP_VAR_ACC_SIZE + case IOCTL_GET_ALL_GNSS_SAT_INFO: + #endif return MBG_REQ_PRIVL_NONE; // Commands returning device capabilities and features: @@ -779,6 +1030,7 @@ int ioctl_get_required_privilege( ulong ioctl_code ) case IOCTL_DEV_IS_MSF: case IOCTL_DEV_IS_WWVB: case IOCTL_DEV_IS_LWR: + case IOCTL_DEV_IS_GNSS: case IOCTL_DEV_IS_IRIG_RX: case IOCTL_DEV_HAS_HR_TIME: case IOCTL_DEV_HAS_CAB_LEN: @@ -817,6 +1069,9 @@ int ioctl_get_required_privilege( ulong ioctl_code ) case IOCTL_DEV_HAS_TR_DISTANCE: case IOCTL_DEV_HAS_DEBUG_STATUS: case IOCTL_DEV_HAS_EVT_LOG: + case IOCTL_DEV_HAS_GPIO: + case IOCTL_DEV_HAS_XMR: + case IOCTL_CHK_DEV_FEAT: return MBG_REQ_PRIVL_NONE; // The next codes are somewhat special since they change something @@ -863,7 +1118,15 @@ int ioctl_get_required_privilege( ulong ioctl_code ) case IOCTL_GET_GPS_ALL_PORT_INFO: case IOCTL_GET_GPS_ALL_POUT_INFO: case IOCTL_GET_ALL_PTP_UC_MASTER_INFO: + case IOCTL_GET_ALL_GPIO_INFO: + case IOCTL_GET_ALL_GPIO_STATUS: + case IOCTL_GET_ALL_XMR_STATUS: + case IOCTL_GET_ALL_XMR_INFO: #endif + case IOCTL_GET_GNSS_MODE_INFO: + case IOCTL_GET_GPIO_CFG_LIMITS: + case IOCTL_GET_XMR_INSTANCES: + case IOCTL_GET_XMR_HOLDOVER_STATUS: return MBG_REQ_PRIVL_CFG_READ; // Writing device configuration: @@ -885,6 +1148,8 @@ int ioctl_get_required_privilege( ulong ioctl_code ) case IOCTL_SET_PTP_CFG_SETTINGS: case IOCTL_SET_PTP_UC_MASTER_SETTINGS_IDX: case IOCTL_SET_TR_DISTANCE: + case IOCTL_SET_GNSS_MODE_SETTINGS: + case IOCTL_SET_GPIO_SETTINGS_IDX: return MBG_REQ_PRIVL_CFG_WRITE; // Operations which may severely affect system operation: @@ -895,6 +1160,7 @@ int ioctl_get_required_privilege( ulong ioctl_code ) case IOCTL_SET_GPS_TIME_SCALE_SETTINGS: case IOCTL_SET_GPS_UTC_PARM: case IOCTL_SET_GPS_CMD: + case IOCTL_SET_XMR_SETTINGS_IDX: // generic write operations can do anything case IOCTL_PCPS_GENERIC_WRITE: case IOCTL_PCPS_GENERIC_WRITE_GPS: @@ -917,6 +1183,7 @@ int ioctl_get_required_privilege( ulong ioctl_code ) case IOCTL_MBG_DBG_CLR_ALL: return MBG_REQ_PRIVL_SYSTEM; #endif + } // switch return -1; // unsupported code, should always be denied @@ -925,24 +1192,13 @@ int ioctl_get_required_privilege( ulong ioctl_code ) -/* End of header body */ - -#undef _ext -#undef _DO_INIT - - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ -/* (no header definitions found) */ + int mbgioctl_rc_to_mbg_errno( int sys_errno ) ; + const char *mbgioctl_get_name( long code ) ; /* ----- function prototypes end ----- */ @@ -951,4 +1207,9 @@ extern "C" { #endif +/* End of header body */ + +#undef _ext +#undef _DO_INIT + #endif /* _MBGIOCTL_H */ diff --git a/c/mbglib/include/mbgirig.h b/c/mbglib/include/mbgirig.h deleted file mode 100644 index 8caa50b..0000000 --- a/c/mbglib/include/mbgirig.h +++ /dev/null @@ -1,467 +0,0 @@ - -/************************************************************************** - * - * $Id: mbgirig.h 1.2 2014/03/18 16:47:34Z martin TRASH $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes used with IRIG and similar timecodes. - * - * ----------------------------------------------------------------------- - * $Log: mbgirig.h $ - * Revision 1.2 2014/03/18 16:47:34Z martin - * Support IEEE C37.118.1-2011 CTQ. - * Revision 1.1 2013/09/02 16:11:54Z martin - * Initial revision. - * - **************************************************************************/ - -#ifndef _MBGIRIG_H -#define _MBGIRIG_H - - -/* Other headers to be included */ - -#include <mbg_tgt.h> -#include <gpsdefs.h> - - -#ifdef _MBGIRIG - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment - #define _USING_BYTE_ALIGNMENT -#endif - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * @brief Get a particular bit from ::MBG_RAW_IRIG_DATA - * - * @param[in] idx The index number of the raw IRIG bits - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return 0 or 1, depending on the bit level - */ -static __mbg_inline -int mbg_decode_raw_irig_bit( int idx, const MBG_RAW_IRIG_DATA *p ) -{ - return ( p->data_bytes[idx >> 3] >> ( 7 - ( idx & 7 ) ) ) & 0x01; - -} // mbg_decode_raw_irig_bit - - - -/** - * @brief Decode a particular value from ::MBG_RAW_IRIG_DATA - * - * @param[in] first_idx Index number of the first bit to decode - * @param[in] num_bits Number of sequential bits to decode - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -long mbg_decode_raw_irig_val( int first_idx, int num_bits, const MBG_RAW_IRIG_DATA *p ) -{ - long ret_val = 0; - int i; - - for ( i = 0; i < num_bits; i++ ) - ret_val |= ( ( (long) mbg_decode_raw_irig_bit( first_idx + i, p ) ) << i ); - - return ret_val; - -} // mbg_decode_raw_irig_val - - - -/** - * @brief Decode the seconds field from ::MBG_RAW_IRIG_DATA - * - * This is supported for IRIG / IEEE / Afnor code formats. - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -int mbg_decode_raw_irig_sec( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_val( 1, 4, p ) - + mbg_decode_raw_irig_val( 6, 3, p ) * 10; - -} // mbg_decode_raw_irig_sec - - - -/** - * @brief Decode the minutes field from ::MBG_RAW_IRIG_DATA - * - * This is supported for IRIG / IEEE / Afnor code formats. - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -int mbg_decode_raw_irig_min( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_val( 10, 4, p ) - + mbg_decode_raw_irig_val( 15, 3, p ) * 10; - -} // mbg_decode_raw_irig_min - - - -/** - * @brief Decode the hours field from ::MBG_RAW_IRIG_DATA - * - * This is supported for IRIG / IEEE / Afnor code formats. - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -int mbg_decode_raw_irig_hour( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_val( 20, 4, p ) - + mbg_decode_raw_irig_val( 25, 2, p ) * 10; - -} // mbg_decode_raw_irig_hour - - - -/** - * @brief Decode the yday (day-of-year) field from ::MBG_RAW_IRIG_DATA - * - * This is supported for IRIG / IEEE / Afnor code formats. - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -int mbg_decode_raw_irig_yday( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_val( 30, 4, p ) - + mbg_decode_raw_irig_val( 35, 4, p ) * 10 - + mbg_decode_raw_irig_val( 40, 2, p ) * 100; - -} // mbg_decode_raw_irig_yday - - - -/** - * @brief Decode the straight binary seconds (SBS) field from ::MBG_RAW_IRIG_DATA - * - * @note The returned value is only valid if a code format is received - * which provides this information. - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -long mbg_decode_raw_irig_sbs( const MBG_RAW_IRIG_DATA *p ) -{ - return ( (long) mbg_decode_raw_irig_val( 80, 9, p ) ) - + ( ( (long) mbg_decode_raw_irig_val( 90, 8, p ) ) << 9 ); - -} // mbg_decode_raw_irig_sbs - - - -/** - * @brief Decode the short (2-digit) year number from ::MBG_RAW_IRIG_DATA - * - * @note The returned value is only valid if a code format is received - * which provides this information, see @ref MSK_ICODE_TX_HAS_SHORT_YEAR - * and @ref MSK_ICODE_RX_HAS_SHORT_YEAR - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -long mbg_decode_raw_irig_short_year( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_val( 50, 4, p ) - + mbg_decode_raw_irig_val( 55, 4, p ) * 10; - -} // mbg_decode_raw_irig_short_year - - - -/** - * @brief Decode the leap second announcement bit from ::MBG_RAW_IRIG_DATA - * - * @note The returned value is only valid if a code format is received - * which provides this information, see @ref MSK_ICODE_TX_HAS_TZI and - * @ref MSK_ICODE_RX_HAS_TZI - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return 1 if a leap second is pending, else 0 - */ -static __mbg_inline -int mbg_decode_raw_irig_ls_ann( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_bit( 60, p ); - -} // mbg_decode_raw_irig_ls_ann - - - -/** - * @brief Decode the leap second negative bit from ::MBG_RAW_IRIG_DATA - * - * @note The returned value is only valid if a code format is received - * which provides this information, see @ref MSK_ICODE_TX_HAS_TZI and - * @ref MSK_ICODE_RX_HAS_TZI - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return 1 if a pending leap second is negative (deleted), else 0 (inserted) - */ -static __mbg_inline -int mbg_decode_raw_irig_ls_neg( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_bit( 61, p ); - -} // mbg_decode_raw_irig_ls_neg - - - -/** - * @brief Decode the DST change announcement bit from ::MBG_RAW_IRIG_DATA - * - * @note The returned value is only valid if a code format is received - * which provides this information, see @ref MSK_ICODE_TX_HAS_TZI and - * @ref MSK_ICODE_RX_HAS_TZI - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return 1 if a change in daylight saving is pending - */ -static __mbg_inline -int mbg_decode_raw_irig_dl_ann( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_bit( 62, p ); - -} // mbg_decode_raw_irig_dl_ann - - - -/** - * @brief Decode the DST enabled bit from ::MBG_RAW_IRIG_DATA - * - * @note The returned value is only valid if a code format is received - * which provides this information, see @ref MSK_ICODE_TX_HAS_TZI and - * @ref MSK_ICODE_RX_HAS_TZI - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return 1 if daylight saving is currently active, else 0 - */ -static __mbg_inline -int mbg_decode_raw_irig_dl_enb( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_bit( 63, p ); - -} // mbg_decode_raw_irig_dl_enb - - - -/** - * @brief Decode UTC offset from ::MBG_RAW_IRIG_DATA - * - * This is only supported by some timecode signal formats, - * see @ref MSK_ICODE_TX_HAS_TZI and @ref MSK_ICODE_RX_HAS_TZI - * - * @note The way the UTC offset has to be applied has been reversed in - * IEEE C37.118, which is the successor of the original IEEE 1344 standard. - * - * For example, if a -6 hours UTC offset is transmitted in the time code:<br> - * IEEE 1344: (IRIG time 14:43:27 h) - (offs -6 h) = (UTC 20:43:27)<br> - * IEEE C37.118: (IRIG time 14:43:27 h) + (offs -6 h) = (UTC 08:43:27)<br> - */ -static __mbg_inline -long mbg_decode_raw_irig_utc_offs_sec( const MBG_RAW_IRIG_DATA *p ) -{ - long ret_val = ( (long) mbg_decode_raw_irig_val( 65, 4, p ) ) * SECS_PER_HOUR; - - // a single bit indicates an addition 1/2 hour offset - if ( mbg_decode_raw_irig_bit( 70, p ) ) - ret_val += SECS_PER_HOUR / 2; - - // check the sign bit - if ( mbg_decode_raw_irig_bit( 64, p ) ) - ret_val = -ret_val; - - return ret_val; - -} // mbg_decode_raw_irig_utc_offs_sec - - - -/** - * @brief Decode the Time Figure Of Merit (TFOM) code from ::MBG_RAW_IRIG_DATA - * - * This code reports the time quality from the IRIG generator which is ranging - * from 0x0 (locked, maximum accuracy) to 0xF (failed, data unreliable). - * - * @note The returned value is only valid if a code format is used which supports - * this. See @ref MSK_ICODE_TX_HAS_TFOM and @ref MSK_ICODE_RX_HAS_TFOM - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -int mbg_decode_raw_irig_tfom( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_val( 71, 4, p ); - -} // mbg_decode_raw_irig_tfom - - - -/** - * @brief Decode the Continuous Time Quality (CTQ) code from ::MBG_RAW_IRIG_DATA - * - * IEEE C37.118.1-2011 defines 3 new "Continuous Time Quality, CTQ" bits. - * These bits have been 0 (unused) in earlier IEEE codes. Coding: - * - * 000: not used for CTQ for compatibility with older codes - * 001: estimated time error < 100 ns - * 010: estimated time error < 1 us - * 011: estimated time error < 10 us - * 100: estimated time error < 100 us - * 101: estimated time error < 1 ms - * 110: estimated time error < 10 ms - * 111: estimated time error > 10 ms or unknown - * - * @note The returned value is only valid if a time code format is - * used which supports this (see @ref MSK_ICODE_TX_HAS_CTQ and - * @ref MSK_ICODE_RX_HAS_CTQ), and if also the time code generator - * supports C37.118.1-2011, in which case these 3 bits are never all 0. - * If supported, the bits are active all the time, in locked and - * unlocked generator state. - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -int mbg_decode_raw_irig_ctq( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_val( 76, 3, p ); - -} // mbg_decode_raw_irig_ctq - - - -/** - * @brief Decode the day-of-week number from ::MBG_RAW_IRIG_DATA - * - * @note The returned value is only valid if a code format is received - * which provides this information, see @ref MSK_ICODE_TX_HAS_AFNOR_WDAY - * and @ref MSK_ICODE_RX_HAS_AFNOR_WDAY - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -long mbg_decode_raw_afnor_wday( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_val( 44, 3, p ); - -} // mbg_decode_raw_afnor_wday - - - -/** - * @brief Decode the day-of-month from ::MBG_RAW_IRIG_DATA - * - * @note The returned value is only valid if a code format is received - * which provides this information, see @ref MSK_ICODE_TX_HAS_AFNOR_DATE - * and @ref MSK_ICODE_RX_HAS_AFNOR_DATE - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -long mbg_decode_raw_afnor_mday( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_val( 70, 4, p ) - + mbg_decode_raw_irig_val( 75, 2, p ) * 10; - -} // mbg_decode_raw_afnor_mday - - - -/** - * @brief Decode the month number from ::MBG_RAW_IRIG_DATA - * - * @note The returned value is only valid if a code format is received - * which provides this information, see @ref MSK_ICODE_TX_HAS_AFNOR_DATE - * and @ref MSK_ICODE_RX_HAS_AFNOR_DATE - * - * @param[in] p A ::MBG_RAW_IRIG_DATA structure - * - * @return the decoded value - */ -static __mbg_inline -long mbg_decode_raw_afnor_month( const MBG_RAW_IRIG_DATA *p ) -{ - return mbg_decode_raw_irig_val( 60, 4, p ) - + mbg_decode_raw_irig_val( 65, 1, p ) * 10; - -} // mbg_decode_raw_afnor_month - - - - - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - -/* (no header definitions found) */ - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - - -#if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment - #undef _USING_BYTE_ALIGNMENT -#endif - -/* End of header body */ - - -#undef _ext -#undef _DO_INIT - -#endif /* _MBGIRIG_H */ - diff --git a/c/mbglib/include/mbgklist.h b/c/mbglib/include/mbgklist.h new file mode 100644 index 0000000..f5afcb2 --- /dev/null +++ b/c/mbglib/include/mbgklist.h @@ -0,0 +1,328 @@ + +/************************************************************************** + * + * $Id: mbgklist.h 1.5 2019/08/15 10:33:01Z thomas-b REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Userspace implementation of Linux Kernel's list.h + * + * ----------------------------------------------------------------------- + * $Log: mbgklist.h $ + * Revision 1.5 2019/08/15 10:33:01Z thomas-b + * Start variable names in macros with '_' + * Revision 1.4 2018/09/13 05:27:28 thomas-b + * Added macro to get nth item of mbgklist + * Revision 1.3 2017/07/05 09:52:39 martin + * Safe loop macros added by philipp. + * Check if 'typeof' is supported based on the type of compiler. + * Reformatted code to conform to standard header file format. + * Updated function prototypes. + * Revision 1.2 2015/10/06 07:08:45 philipp + * Added functions to loop containers of list entries + * Revision 1.1 2015/09/09 10:42:27 martin + * Initial revision. + * + **************************************************************************/ + +#ifndef _MBGKLIST_H +#define _MBGKLIST_H + +/* Other headers to be included */ + +#include <mbg_cof.h> + + +#ifdef _MBGKLIST + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +#define MBG_KLIST_INIT(name) { &(name), &(name) } + +#define MBG_KLIST_DECLARE(name) \ + struct mbg_klist_head name = MBG_KLIST_INIT(name) + +#define mbg_klist_for_each(head, pos) \ + for (pos = (head)->next; pos != (head); pos = pos->next) + +#define mbg_klist_for_each_safe(head, pos, n) \ + for (pos = (head)->next, n = (pos)->next; \ + pos != (head); \ + pos = n, n = pos->next) + +#define mbg_klist_for_each_rev(head, pos) \ + for (pos = (head)->prev; pos != (head); pos = pos->prev) + +#define mbg_klist_for_each_rev_safe(head, pos, n) \ + for (pos = (head)->prev, n = (pos)->prev; \ + pos != (head); \ + pos = n, n = pos->prev) + +#define mbg_klist_nth_item(head, pos, n) \ + do { \ + unsigned _i; \ + for (pos = (head)->next, _i = 0; _i < n; pos = pos->next, ++_i); \ + } while ( 0 ) + +#define mbg_klist_entry(ptr, type, member) \ + mbg_container_of(ptr, type, member) + +#define mbg_klist_first_entry(ptr, type, member) \ + mbg_klist_entry((ptr)->next, type, member) + +#define mbg_klist_last_entry(ptr, type, member) \ + mbg_klist_entry((ptr)->prev, type, member) + + + +#if defined( __GNUC__ ) || defined( __clang__ ) // "typeof" supported + +#define mbg_klist_next_entry(pos, member) \ + mbg_klist_entry((pos)->member.next, typeof(*pos), member) + +#define mbg_klist_prev_entry(pos, member) \ + mbg_klist_entry((pos)->member.prev, typeof(*pos), member) + +#define mbg_klist_for_each_entry(head, pos, member) \ + for (pos = mbg_klist_first_entry(head, typeof(*pos), member); \ + &pos->member != (head); \ + pos = mbg_klist_next_entry(pos, member)) + +#define mbg_klist_for_each_entry_rev(head, pos, member) \ + for (pos = mbg_klist_last_entry(head, typeof(*pos), member); \ + &pos->member != (head); \ + pos = mbg_klist_prev_entry(pos, member)) + +#define mbg_klist_for_each_entry_safe(head, pos, n, member) \ + for (pos = mbg_klist_first_entry(head, typeof(*pos), member), \ + n = mbg_klist_next_entry(pos, member); \ + &pos->member != (head); \ + pos = n, n = mbg_klist_next_entry(pos, member)) + +#define mbg_klist_for_each_entry_rev_safe(head, pos, n, member) \ + for (pos = mbg_klist_last_entry(head, typeof(*pos), member), \ + n = mbg_klist_prev_entry(pos, member); \ + &pos->member != (head); \ + pos = n, n = mbg_klist_prev_entry(pos, member)) + +#endif + + + +struct mbg_klist_head +{ + struct mbg_klist_head *prev; + struct mbg_klist_head *next; +}; + + + +static __mbg_inline +void mbg_klist_init( struct mbg_klist_head *head ) +{ + head->next = head; + head->prev = head; +} + + +static __mbg_inline +void __mbg_klist_add_item( struct mbg_klist_head *item, struct mbg_klist_head *prev, struct mbg_klist_head *next ) +{ + next->prev = item; + item->next = next; + item->prev = prev; + prev->next = item; +} + + +static __mbg_inline +void mbg_klist_prepend_item( struct mbg_klist_head *head, struct mbg_klist_head *item ) +{ + __mbg_klist_add_item( item, head, head->next ); +} + + +static __mbg_inline +void mbg_klist_append_item( struct mbg_klist_head *head, struct mbg_klist_head *item ) +{ + __mbg_klist_add_item( item, head->prev, head ); +} + + +static __mbg_inline +void __mbg_klist_delete_item( struct mbg_klist_head *prev, struct mbg_klist_head *next ) +{ + next->prev = prev; + prev->next = next; +} + + +static __mbg_inline +void mbg_klist_delete_item( struct mbg_klist_head *item ) +{ + __mbg_klist_delete_item( item->prev, item->next ); +} + + +static __mbg_inline +void mbg_klist_delete_item_init( struct mbg_klist_head *item ) +{ + __mbg_klist_delete_item( item->prev, item->next ); + mbg_klist_init( item ); +} + + +static __mbg_inline +void mbg_klist_replace_item( struct mbg_klist_head *old, struct mbg_klist_head *item ) +{ + item->next = old->next; + item->next->prev = item; + item->prev = old->prev; + item->prev->next = item; +} + + +static __mbg_inline +void mbg_klist_replace_item_init( struct mbg_klist_head *old, struct mbg_klist_head *item ) +{ + mbg_klist_replace_item( old, item ); + mbg_klist_init( item ); +} + + +static __mbg_inline +void mbg_klist_move_prepend_item( struct mbg_klist_head *head, struct mbg_klist_head *item ) +{ + mbg_klist_delete_item( item ); + mbg_klist_prepend_item( head, item ); +} + + +static __mbg_inline +void mbg_klist_move_append_item( struct mbg_klist_head *head, struct mbg_klist_head *item ) +{ + mbg_klist_delete_item( item ); + mbg_klist_append_item( head, item ); +} + + +static __mbg_inline +int mbg_klist_is_first( const struct mbg_klist_head *head, const struct mbg_klist_head *item ) +{ + return ( ( item->prev == head ) ? 1 : 0 ); +} + + +static __mbg_inline +int mbg_klist_is_last( const struct mbg_klist_head *head, const struct mbg_klist_head *item ) +{ + return ( ( item->next == head ) ? 1 : 0 ); +} + + +static __mbg_inline +int mbg_klist_is_empty( const struct mbg_klist_head *head ) +{ + return ( ( head->next == head ) ? 1 : 0 ); +} + + +static __mbg_inline +void __mbg_klist_add_list( const struct mbg_klist_head *list, struct mbg_klist_head *prev, struct mbg_klist_head *next ) +{ + struct mbg_klist_head *_first = list->next; + struct mbg_klist_head *_last = list->prev; + + _first->prev = prev; + prev->next = _first; + + _last->next = next; + next->prev = _last; +} + + +static __mbg_inline +void mbg_klist_prepend_list( struct mbg_klist_head *head, const struct mbg_klist_head *list ) +{ + if ( !mbg_klist_is_empty( list ) ) + __mbg_klist_add_list( list, head, head->next ); +} + + +static __mbg_inline +void mbg_klist_append_list( struct mbg_klist_head *head, const struct mbg_klist_head *list ) +{ + if ( !mbg_klist_is_empty( list ) ) + __mbg_klist_add_list( list, head->prev, head ); +} + + +static __mbg_inline +void mbg_klist_prepend_list_init( struct mbg_klist_head *head, struct mbg_klist_head *list ) +{ + if ( !mbg_klist_is_empty( list ) ) + { + __mbg_klist_add_list( list, head, head->next ); + mbg_klist_init( list ); + } +} + + +static __mbg_inline +void mbg_klist_append_list_init( struct mbg_klist_head *head, struct mbg_klist_head *list ) +{ + if ( !mbg_klist_is_empty( list ) ) + { + __mbg_klist_add_list( list, head->prev, head ); + mbg_klist_init( list ); + } +} + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + /** + * @brief Sort a list + * + * @param[in] priv Private data, opaque to ::mbg_klist_sort, passed to @p cmp + * @param[in] head The list to sort + * @param[in] cmp The elements comparison function + * + * This function implements "merge sort", which has O(nlog(n)) + * complexity. + * + * The comparison function @p cmp must return a negative value if a + * should sort before b, and a positive value if a should sort after + * b. If a and b are equivalent, and their original relative + * ordering is to be preserved, cmp must return 0. + */ + void mbg_klist_sort( void *priv, struct mbg_klist_head *head, int (*cmp)( void *priv, struct mbg_klist_head *a, struct mbg_klist_head *b ) ) ; + + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _MBGKLIST_H */ diff --git a/c/mbglib/include/mbgmutex.h b/c/mbglib/include/mbgmutex.h index b0d2e7a..7a39075 100644 --- a/c/mbglib/include/mbgmutex.h +++ b/c/mbglib/include/mbgmutex.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgmutex.h 1.3.1.2 2014/03/04 12:08:12Z martin TRASH $ + * $Id: mbgmutex.h 1.5 2018/07/16 14:18:05Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -11,9 +11,11 @@ * * ----------------------------------------------------------------------- * $Log: mbgmutex.h $ - * Revision 1.3.1.2 2014/03/04 12:08:12Z martin - * Revision 1.3.1.1 2014/01/08 17:20:57Z martin - * MBG_TGT_POSIX + * Revision 1.5 2018/07/16 14:18:05Z martin + * Support ID strings for spinlocks and mutexes. + * Revision 1.4 2017/07/05 10:05:02 martin + * windows.h is now included by mbg_tgt.h. + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. * Revision 1.3 2013/04/11 13:46:58 martin * Use non-specific spinlock function under Windows. * Revision 1.2 2012/03/08 12:19:01Z martin @@ -45,12 +47,16 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + #if defined( MBG_TGT_KERNEL ) // definitions used in kernel space #if defined( MBG_TGT_WIN32 ) // Windows kernel space typedef KSPIN_LOCK MBG_SPINLOCK; - #define _mbg_spin_lock_init( _spl ) KeInitializeSpinLock( _spl ) + #define _mbg_spin_lock_init( _spl, _n ) KeInitializeSpinLock( _spl ) // _mbg_spin_lock_destroy is not supported #define _mbg_spin_lock_acquire( _spl ) KeAcquireSpinLock( _spl, &OldIrql ) #define _mbg_spin_lock_release( _spl ) KeReleaseSpinLock( _spl, OldIrql ) @@ -59,7 +65,7 @@ typedef FAST_MUTEX MBG_MUTEX; - #define _mbg_mutex_init( _pmtx ) ExInitializeFastMutex( _pmtx ) + #define _mbg_mutex_init( _pmtx, _n ) ExInitializeFastMutex( _pmtx ) // _mbg_mutex_destroy( _pmtx ) is not supported #define _mbg_mutex_acquire( _pmtx ) ExAcquireFastMutex( _pmtx ) #define _mbg_mutex_release( _pmtx ) ExReleaseFastMutex( _pmtx ) @@ -78,7 +84,7 @@ #endif typedef spinlock_t MBG_SPINLOCK; - #define _mbg_spin_lock_init( _spl ) spin_lock_init( _spl ) + #define _mbg_spin_lock_init( _spl, _n ) spin_lock_init( _spl ) // _mbg_spin_lock_destroy is not supported #define _mbg_spin_lock_acquire( _spl ) spin_lock( _spl ) #define _mbg_spin_lock_release( _spl ) spin_unlock( _spl ) @@ -87,7 +93,7 @@ typedef struct semaphore MBG_MUTEX; - #define _mbg_mutex_init( _pmtx ) sema_init( _pmtx, 1 ) + #define _mbg_mutex_init( _pmtx, _n ) sema_init( _pmtx, 1 ) // _mbg_mutex_destroy( _pmtx ) is not supported #define _mbg_mutex_acquire( _pmtx ) down_interruptible( _pmtx ) #define _mbg_mutex_release( _pmtx ) up( _pmtx ) @@ -100,7 +106,7 @@ #include <sys/mutex.h> typedef struct mtx MBG_SPINLOCK; - #define _mbg_spin_lock_init( _spl ) mtx_init( _spl, "mbg_spin_lock", NULL, MTX_SPIN ) + #define _mbg_spin_lock_init( _spl, _n ) mtx_init( _spl, _n, NULL, MTX_SPIN ) #define _mbg_spin_lock_destroy( _spl ) mtx_destroy( _spl ) #define _mbg_spin_lock_acquire( _spl ) mtx_lock_spin( _spl ) #define _mbg_spin_lock_release( _spl ) mtx_unlock_spin( _spl ) @@ -109,7 +115,7 @@ typedef struct mtx MBG_MUTEX; - #define _mbg_mutex_init( _pmtx ) mtx_init( _pmtx, "mbg_mutex", NULL, MTX_DEF ) + #define _mbg_mutex_init( _pmtx, _n ) mtx_init( _pmtx, _n, NULL, MTX_DEF ) #define _mbg_mutex_destroy( _pmtx ) mtx_destroy( _pmtx ) #define _mbg_mutex_acquire( _pmtx ) mtx_lock( _pmtx ) #define _mbg_mutex_release( _pmtx ) mtx_unlock( _pmtx ) @@ -124,7 +130,7 @@ // For earlier NetBSD versions see 'man 9 lockinit'. typedef kmutex_t MBG_SPINLOCK; - #define _mbg_spin_lock_init( _spl ) mutex_init( _spl, MUTEX_DEFAULT, IPL_HIGH ) + #define _mbg_spin_lock_init( _spl, _n ) mutex_init( _spl, MUTEX_DEFAULT, IPL_HIGH ) #define _mbg_spin_lock_destroy( _spl ) mutex_destroy( _spl ) #define _mbg_spin_lock_acquire( _spl ) mutex_spin_enter( _spl ) #define _mbg_spin_lock_release( _spl ) mutex_spin_exit( _spl ) @@ -133,7 +139,7 @@ typedef kmutex_t MBG_MUTEX; - #define _mbg_mutex_init( _pmtx ) mutex_init( _pmtx, MUTEX_DEFAULT, IPL_NONE ) + #define _mbg_mutex_init( _pmtx, _n ) mutex_init( _pmtx, MUTEX_DEFAULT, IPL_NONE ) #define _mbg_mutex_destroy( _spl ) mutex_destroy( _spl ) #define _mbg_mutex_acquire( _pmtx ) mutex_enter( _pmtx ) #define _mbg_mutex_release( _pmtx ) mutex_exit( _pmtx ) @@ -148,8 +154,8 @@ // definitions used with mutexes typedef HANDLE MBG_MUTEX; - #define _mbg_mutex_init( _pm ) *(_pm) = CreateMutex( NULL, FALSE, NULL ) - #define _mbg_mutex_destroy( _pm ) CloseHandle( *(_pm) ); *(_pm) = INVALID_HANDLE_VALUE + #define _mbg_mutex_init( _pm, _n ) *(_pm) = CreateMutex( NULL, FALSE, NULL ) + #define _mbg_mutex_destroy( _pm ) do { CloseHandle( *(_pm) ); *(_pm) = INVALID_HANDLE_VALUE; } while ( 0 ) #define _mbg_mutex_acquire( _pm ) WaitForSingleObject( *(_pm), INFINITE ) #define _mbg_mutex_release( _pm ) ReleaseMutex( *(_pm) ) @@ -157,7 +163,7 @@ // definitions used with critical sections typedef CRITICAL_SECTION MBG_CRIT_SECT; - #define _mbg_crit_sect_init( _pcs ) InitializeCriticalSection( (_pcs) ) + #define _mbg_crit_sect_init( _pcs, _n ) InitializeCriticalSection( (_pcs) ) #define _mbg_crit_sect_destroy( _pcs ) DeleteCriticalSection( (_pcs) ) #define _mbg_crit_sect_enter( _pcs ) EnterCriticalSection( (_pcs) ) #define _mbg_crit_sect_leave( _pcs ) LeaveCriticalSection( (_pcs) ) @@ -173,7 +179,7 @@ // PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP /* Recursive */ // PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP /* Errorcheck */ typedef pthread_mutex_t MBG_MUTEX; - #define _mbg_mutex_init( _pm ) pthread_mutex_init( (_pm), NULL ) + #define _mbg_mutex_init( _pm, _n ) pthread_mutex_init( (_pm), NULL ) #define _mbg_mutex_destroy( _pm ) pthread_mutex_destroy( (_pm) ) #define _mbg_mutex_acquire( _pm ) pthread_mutex_lock( (_pm) ) #define _mbg_mutex_release( _pm ) pthread_mutex_unlock( (_pm) ) @@ -195,10 +201,10 @@ #if !defined( _MBG_SPINLOCK_DEFINED ) - #define _mbg_spin_lock_init( _spl ) _nop_macro_fnc() - // _mbg_spin_lock_destroy is not supported - #define _mbg_spin_lock_acquire( _spl ) _nop_macro_fnc() - #define _mbg_spin_lock_release( _spl ) _nop_macro_fnc() + #define _mbg_spin_lock_init( _spl, _n ) _nop_macro_fnc() + // _mbg_spin_lock_destroy is not supported + #define _mbg_spin_lock_acquire( _spl ) _nop_macro_fnc() + #define _mbg_spin_lock_release( _spl ) _nop_macro_fnc() #endif @@ -209,7 +215,7 @@ typedef MBG_CRIT_SECT MBG_MUTEX; - #define _mbg_mutex_init( _pm ) _nop_macro_fnc() + #define _mbg_mutex_init( _pm, _n ) _nop_macro_fnc() // _mbg_mutex_destroy( _pmtx ) is not supported #define _mbg_mutex_acquire( _pm ) _nop_macro_fnc() #define _mbg_mutex_release( _pm ) _nop_macro_fnc() @@ -234,13 +240,6 @@ #endif - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/c/mbglib/include/mbgpccyc.h b/c/mbglib/include/mbgpccyc.h index d32e21e..842fe32 100644 --- a/c/mbglib/include/mbgpccyc.h +++ b/c/mbglib/include/mbgpccyc.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgpccyc.h 1.2.1.1 2014/01/08 17:21:03Z martin TRASH $ + * $Id: mbgpccyc.h 1.8 2019/03/18 08:58:39Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,8 +10,18 @@ * * ----------------------------------------------------------------------- * $Log: mbgpccyc.h $ - * Revision 1.2.1.1 2014/01/08 17:21:03Z martin - * MBG_TGT_POSIX + * Revision 1.8 2019/03/18 08:58:39Z martin + * Cleanup and comments. + * Revision 1.7 2017/05/10 15:21:41 martin + * Tiny cleanup. + * Revision 1.6 2016/08/09 16:01:10 martin + * Syntax fix. + * Revision 1.5 2016/02/17 16:04:18 martin + * Include header file missing for FreeBSD. + * Revision 1.4 2015/10/19 09:16:45 martin + * Fixed some spelling. + * Revision 1.3 2014/10/08 13:10:14 martin + * Check for MBG_TGT_POSIX instead of MBG_TGT_UNIX. * Revision 1.2 2012/03/12 13:45:57 martin * Added cycles support for Linux/IA64, FreeBSD and NetBSD * in kernel space. @@ -34,14 +44,15 @@ #if defined( MBG_TGT_NETBSD ) #if defined( MBG_TGT_KERNEL ) #include <machine/cpu.h> - #include <machine/cpu_counter.h> /* for cycle counter abstraction */ + #include <machine/cpu_counter.h> // for cycle counter abstraction #endif #endif #if defined( MBG_TGT_FREEBSD ) #if defined( MBG_TGT_KERNEL ) #if defined( MBG_ARCH_X86 ) - #include <machine/clock.h> /* for symbol 'tsc_freq' */ + #include <sys/time.h> + #include <machine/clock.h> // for symbol 'tsc_freq' #endif #endif #endif @@ -63,13 +74,25 @@ /* Start of header body */ +#ifdef __cplusplus +extern "C" { +#endif + /** * @brief Generic types to hold PC cycle counter values. * * The cycle counter value is usually derived from the PC CPU's TSC or some other * timer hardware on the mainboard. */ -#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_POSIX ) +#if defined( MBG_TGT_WIN32 ) + + // On Windows, QPC() is commonly used to retrieve a cycles count + // as LARGE_INTEGER union which has a LONGLONG QuadPart field, + // which in fact is a signed 64 bit integer. + typedef int64_t MBG_PC_CYCLES; + typedef uint64_t MBG_PC_CYCLES_FREQUENCY; + +#elif defined( MBG_TGT_POSIX ) typedef int64_t MBG_PC_CYCLES; typedef uint64_t MBG_PC_CYCLES_FREQUENCY; @@ -84,6 +107,7 @@ // MBG_PC_CYCLES and MBG_PC_CYCLES_FREQUENCY are always read in native // machine endianess, so no endianess conversion is required. + #define _mbg_swab_mbg_pc_cycles( _p ) \ _nop_macro_fnc() @@ -106,7 +130,7 @@ // which would copy the output regs edx:eax as a 64 bit // number to a variable x. // - // The "=A" expression should implicitely tell the compiler + // The "=A" expression should implicitly tell the compiler // the edx and eax registers have been clobbered. However, // this does not seem to work properly at least with gcc 4.1.2 // shipped with Centos 5. @@ -118,14 +142,14 @@ // assumes edx is unchanged, which may yield faulty results // or even lead to segmentation faults. // - // A possible workaround could be to mark edx explicitely as + // A possible workaround could be to mark edx explicitly as // being clobbered in the asm inline code, but unfortunately // other gcc versions report an error if a register which is - // implicitely (by "=A") known to be clobbered is also listed - // explicitely to be clobbered. + // implicitly (by "=A") known to be clobbered is also listed + // explicitly to be clobbered. // // So the code below is a workaround which tells the compiler - // implicitely that the eax ("=a") and edx ("=d") registers + // implicitly that the eax ("=a") and edx ("=d") registers // are being used and thus clobbered. union @@ -153,59 +177,62 @@ static __mbg_inline void mbg_get_pc_cycles( MBG_PC_CYCLES *p ) { -#if !defined( OMIT_PC_CYCLES_SUPPORT ) + #if !defined( OMIT_PC_CYCLES_SUPPORT ) - #if defined( MBG_TGT_WIN32 ) + #if defined( MBG_TGT_WIN32 ) - #if defined( MBG_TGT_KERNEL ) // kernel space - *p = (MBG_PC_CYCLES) KeQueryPerformanceCounter( NULL ).QuadPart; - #else // user space - QueryPerformanceCounter( (LARGE_INTEGER *) p ); - #endif + #if defined( MBG_TGT_KERNEL ) // kernel space + *p = (MBG_PC_CYCLES) KeQueryPerformanceCounter( NULL ).QuadPart; + #else // user space + // Please note QPC() *may* fail if p points to a variable + // that is *not* at least 4-byte-aligned. + QueryPerformanceCounter( (LARGE_INTEGER *) p ); + #endif - #define MBG_PC_CYCLES_SUPPORTED 1 + #define MBG_PC_CYCLES_SUPPORTED 1 - #elif defined( MBG_TGT_LINUX ) && defined( MBG_ARCH_X86 ) + #elif defined( MBG_TGT_LINUX ) && defined( MBG_ARCH_X86 ) - *p = mbg_rdtscll(); - #define MBG_PC_CYCLES_SUPPORTED 1 + *p = mbg_rdtscll(); + #define MBG_PC_CYCLES_SUPPORTED 1 - #elif defined( MBG_TGT_LINUX ) && defined( MBG_ARCH_IA64 ) && defined( MBG_TGT_KERNEL ) + #elif defined( MBG_TGT_LINUX ) && defined( MBG_ARCH_IA64 ) && defined( MBG_TGT_KERNEL ) - unsigned long result = ia64_getreg( _IA64_REG_AR_ITC ); - ia64_barrier(); + unsigned long result = ia64_getreg( _IA64_REG_AR_ITC ); + ia64_barrier(); - #ifdef CONFIG_ITANIUM - while (unlikely((__s32) result == -1)) { - result = ia64_getreg(_IA64_REG_AR_ITC); - ia64_barrier(); - } - #endif + #ifdef CONFIG_ITANIUM + while (unlikely((__s32) result == -1)) + { + result = ia64_getreg(_IA64_REG_AR_ITC); + ia64_barrier(); + } + #endif - *p = result; + *p = result; - #define MBG_PC_CYCLES_SUPPORTED 1 + #define MBG_PC_CYCLES_SUPPORTED 1 - #elif defined( MBG_TGT_LINUX ) && defined( MBG_TGT_KERNEL ) + #elif defined( MBG_TGT_LINUX ) && defined( MBG_TGT_KERNEL ) - *p = get_cycles(); - #define MBG_PC_CYCLES_SUPPORTED 1 + *p = get_cycles(); + #define MBG_PC_CYCLES_SUPPORTED 1 - #elif defined( MBG_TGT_FREEBSD ) && defined( MBG_ARCH_X86 ) + #elif defined( MBG_TGT_FREEBSD ) && defined( MBG_ARCH_X86 ) - *p = mbg_rdtscll(); + *p = mbg_rdtscll(); - #define MBG_PC_CYCLES_SUPPORTED 1 + #define MBG_PC_CYCLES_SUPPORTED 1 - #elif defined( MBG_TGT_NETBSD ) && defined ( MBG_TGT_KERNEL ) + #elif defined( MBG_TGT_NETBSD ) && defined( MBG_TGT_KERNEL ) - *p = cpu_counter(); //##++ or cpu_counter_serializing() + *p = cpu_counter(); // TODO or cpu_counter_serializing()? - #define MBG_PC_CYCLES_SUPPORTED 1 + #define MBG_PC_CYCLES_SUPPORTED 1 - #endif + #endif -#endif + #endif #if !defined( MBG_PC_CYCLES_SUPPORTED ) @@ -239,7 +266,8 @@ void mbg_get_pc_cycles_frequency( MBG_PC_CYCLES_FREQUENCY *p ) #elif defined( MBG_TGT_LINUX ) && defined( MBG_ARCH_IA64 ) - // we probably can use + // TODO we probably can use: + // // ia64_sal_freq_base(unsigned long which, unsigned long *ticks_per_second, // unsigned long *drift_info) // However, this is not tested. @@ -267,25 +295,12 @@ void mbg_get_pc_cycles_frequency( MBG_PC_CYCLES_FREQUENCY *p ) static __mbg_inline MBG_PC_CYCLES mbg_delta_pc_cycles( const MBG_PC_CYCLES *p1, const MBG_PC_CYCLES *p2 ) { -#if 0 && !MBG_PC_CYCLES_SUPPORTED - // Cycle counts not supported on this target platform. - // Under SPARC this may even result in bus errors - // due to alignment of the underlying data structures. - return 0; -#else return *p1 - *p2; -#endif } // mbg_delta_pc_cycles -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ diff --git a/c/mbglib/include/mbgserio.h b/c/mbglib/include/mbgserio.h deleted file mode 100644 index a0d9314..0000000 --- a/c/mbglib/include/mbgserio.h +++ /dev/null @@ -1,192 +0,0 @@ - -/************************************************************************** - * - * $Id: mbgserio.h 1.6.1.5 2011/12/15 14:20:58Z martin TEST $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for mbgserio.c. - * - * ----------------------------------------------------------------------- - * $Log: mbgserio.h $ - * Revision 1.6.1.5 2011/12/15 14:20:58Z martin - * Tmp. debug code to test flush under Windows. - * Revision 1.6.1.4 2011/12/13 08:36:50Z martin - * Got rid of _mbg_open/clos/read/write() macros. - * Revision 1.6.1.3 2011/12/13 08:24:56 martin - * Removed most _mbgderio_...() function macros. - * Revision 1.6.1.2 2011/12/12 17:20:24 martin - * Revision 1.6.1.1 2011/12/12 16:12:25 martin - * Started to get rid of _mbgserio_read/write macros. - * Use functions instead. - * Revision 1.6 2011/08/23 10:15:25Z martin - * Updated function prototypes. - * Revision 1.5 2011/08/04 09:48:55 martin - * Support flushing output. - * Re-ordered some definitions. - * Revision 1.4 2009/09/01 10:54:29 martin - * Include mbg_tmo.h for the new portable timeout functions. - * Added symbols for return codes in case of an error. - * Code cleanup. - * Revision 1.3 2009/04/01 14:17:31 martin - * Cleanup for CVI. - * Revision 1.2 2008/09/04 15:11:36Z martin - * Preliminary support for device lists. - * Updated function prototypes. - * Revision 1.1 2007/11/12 16:48:02 martin - * Initial revision. - * - **************************************************************************/ - -#ifndef _MBGSERIO_H -#define _MBGSERIO_H - - -/* Other headers to be included */ - -#include <mbg_tmo.h> - -#include <stdlib.h> -#include <string.h> - -#if defined( MBG_TGT_UNIX ) - #include <termios.h> -#endif - -#if _USE_CHK_TSTR - #include <chk_tstr.h> -#endif - -#if !defined( _USE_SELECT_FOR_SERIAL_IO ) - #if defined( MBG_TGT_UNIX ) - #define _USE_SELECT_FOR_SERIAL_IO 1 - #else - #define _USE_SELECT_FOR_SERIAL_IO 0 - #endif -#endif - - -#ifdef _MBGSERIO - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#define MBGSERIO_FAIL -1 // Generic I/O error -#define MBGSERIO_TIMEOUT -2 // timeout -#define MBGSERIO_INV_CFG -3 // invalid configuration parameters - - -#if !defined( DEFAULT_DEV_NAME ) - #if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_DOS ) - #define DEFAULT_DEV_NAME "COM1" - #elif defined( MBG_TGT_LINUX ) - #define DEFAULT_DEV_NAME "/dev/ttyS0" - #endif -#endif - - -/* - * The following macros control parts of the build process. - * The default values are suitable for most cases but can be - * overridden by global definitions, if required. - */ - -#if _IS_MBG_FIRMWARE - - // This handle type in not used by the firmware. - // However, we define it to avoid build errors. - typedef int MBG_HANDLE; - -#else - - #if defined( MBG_TGT_CVI ) - - #include <rs232.h> - - #elif defined( MBG_TGT_WIN32 ) - - #include <windows.h> - #include <io.h> - - #elif defined( MBG_TGT_UNIX ) - - #include <unistd.h> - - #elif defined( MBG_TGT_DOS ) - - #if defined( _USE_V24TOOLS ) - #include <v24tools.h> - #endif - - #endif - -#endif - - - -typedef struct _MBG_STR_LIST -{ - char *s; - struct _MBG_STR_LIST *next; - -} MBG_STR_LIST; - - - -typedef struct -{ - MBG_PORT_HANDLE port_handle; // the handle that will be used for the device - - #if defined( MBG_TGT_WIN32 ) - DCB old_dcb; - COMMTIMEOUTS old_commtimeouts; - COMMPROP comm_prop; - #endif - - #if defined( MBG_TGT_UNIX ) - struct termios old_tio; - #endif - -} SERIAL_IO_STATUS; - - - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - _NO_MBG_API_ATTR int _MBG_API mbgserio_open( SERIAL_IO_STATUS *pst, const char *dev ) ; - _NO_MBG_API_ATTR int _MBG_API mbgserio_close( SERIAL_IO_STATUS *pst ) ; - _NO_MBG_API_ATTR int _MBG_API mbgserio_setup_port_str_list( MBG_STR_LIST **list, int max_devs ) ; - _NO_MBG_API_ATTR void _MBG_API mbgserio_free_str_list( MBG_STR_LIST *list ) ; - _NO_MBG_API_ATTR int _MBG_API mbgserio_set_parms( SERIAL_IO_STATUS *pst, uint32_t baud_rate, const char *framing ) ; - _NO_MBG_API_ATTR int _MBG_API mbgserio_read( MBG_PORT_HANDLE h, void *buffer, unsigned int count ) ; - _NO_MBG_API_ATTR int _MBG_API mbgserio_write( MBG_PORT_HANDLE h, const void *buffer, unsigned int count ) ; - _NO_MBG_API_ATTR void _MBG_API mbgserio_flush_tx( MBG_PORT_HANDLE h ) ; - _NO_MBG_API_ATTR int _MBG_API mbgserio_read_wait( MBG_PORT_HANDLE h, void *buffer, uint count, ulong char_timeout ) ; - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - -/* End of header body */ - -#undef _ext -#undef _DO_INIT - -#endif /* _MBGSERIO_H */ diff --git a/c/mbglib/include/mbgsvcio.h b/c/mbglib/include/mbgsvcio.h index 83161ef..c1dee47 100644 --- a/c/mbglib/include/mbgsvcio.h +++ b/c/mbglib/include/mbgsvcio.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgsvcio.h 1.16.1.3 2012/10/17 12:45:11Z martin TRASH $ + * $Id: mbgsvcio.h 1.18.1.4 2019/01/21 16:57:44Z martin.burnicki TEST $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,10 +10,21 @@ * * ----------------------------------------------------------------------- * $Log: mbgsvcio.h $ - * Revision 1.16.1.3 2012/10/17 12:45:11Z martin - * Fixed doxygen comments. - * Revision 1.16.1.2 2010/01/08 15:04:38Z martin - * Revision 1.16.1.1 2010/01/07 16:24:56Z martin + * Revision 1.18.1.4 2019/01/21 16:57:44Z martin.burnicki + * FT_DWL::dwl is now an int64_t instead of an uint64_t. + * Revision 1.18.1.3 2019/01/18 15:31:44 martin.burnicki + * Tmp. saved state. + * Revision 1.18.1.2 2019/01/17 10:51:54 martin.burnicki + * MBG_TIME_INFO was renamed to FT_DWL_EX. + * Revision 1.18.1.1 2019/01/16 17:09:52 martin + * REF_TIME was renamed to MBG_TIME_INFO. + * Revision 1.18 2018/09/21 07:39:14Z martin + * New version code 308, compatibility version code still 200. + * New define USE_SERIAL_XHRT, still 0 by default. + * Updated function prototypes. + * Revision 1.17 2014/07/10 15:03:14Z martin + * Moved some definitions here. + * Updated function prototypes. * Revision 1.16 2009/08/14 09:28:13Z daniel * New version code 306, compatibility version code still 200. * Revision 1.15 2009/06/09 08:57:47Z daniel @@ -57,9 +68,10 @@ /* Other headers to be included */ #include <mbg_tgt.h> -#include <mbgdevio.h> // for mutex support only -#include <timecnv.h> // for REF_TIME only - +#include <words.h> +#include <pcpsdefs.h> +#include <mbgdevio.h> // for MBG_XHRT_VARS +#include <mbgpccyc.h> #ifdef _MBGSVCIO @@ -75,147 +87,259 @@ #pragma pack( 1 ) #endif -#define MBGSVCIO_VERSION 0x0306 +#define MBGSVCIO_VERSION 0x0308 #define MBGSVCIO_COMPAT_VERSION 0x0200 +#define USE_SERIAL_XHRT 0 // FIXME should be 0 by default // not fully implemented/tested + #ifdef __cplusplus extern "C" { #endif -/* ----- function prototypes begin ----- */ +/** + * @brief A union used to access a FILETIME as 64 bit number + * + * @note using this union may be tricky. Even though no problems + * have been observed, yet, the MS docs clearly say there may be + * alignment problems under 64 bit Windows. + * If the FILETIME members are not 32 bit aligned then accessing + * the dwl member will yield wrong values. + */ +typedef union +{ + FILETIME ft; ///< FILETIME structure as provided by the Windows API + int64_t dwl; ///< used to access as single 64 bit number -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ +} FT_DWL; - /** - Get the version number of the compiled mbgsvcio library. - If the mbgsvcio library is built as a DLL then - the version number of the compiled library may differ from - the version number of the import library and header files - which have been used to build an application. - @return The version number - @see ::MBGSVCIO_VERSION defined in mbgsvcio.h. -*/ - _MBG_API_ATTR int _MBG_API mbgsvcio_get_version( void ) ; +/** + * @brief A timestamp in Windows format, plus %UTC offset and clock status + */ +typedef struct +{ + FT_DWL ftdwl; ///< time stamp, based on %UTC + int32_t utc_offs; ///< %UTC offset in [sec] + PCPS_TIME_STATUS_X status; ///< extended status, see ::PCPS_TIME_STATUS_X - /** - Check if the version of the compiled mbgsvcio library is compatible - with a certain version which is passed as parameter. +} FT_DWL_EX; - @param header_version Version number to be checked, should be ::MBGSVCIO_VERSION - defined in mbgsvcio.h. - @return ::MBG_SUCCESS if compatible, ::MBG_WINERR_LIB_NOT_COMPATIBLE if not. - @see ::MBGSVCIO_VERSION defined in mbgsvcio.h. - */ - _MBG_API_ATTR int _MBG_API mbgsvcio_check_version( int header_version ) ; +/** + * @brief An extended timestamp plus associated machine cycles. + */ +typedef struct +{ + MBG_PC_CYCLES cycles; + FT_DWL_EX ft_ex; - /** - Query the status of the Meinberg time adjustment service "mbgadjtm.exe" +} FT_DWL_EX_CYCLES; - @return 1, if the service has the state "SERVICE_RUNNING", otherwise 0. -*/ - _MBG_API_ATTR int _MBG_API mbg_time_adjustment_active( void ) ; - /** - Check if the time of the reference clock is accessible. - @return 1: The reference clock is accessible and delivers a valid time.<br> - 0: The reference time is invalid or inaccessible.<br> - -1: The shared memory area which provides information from the - service is not accessible.<br> -*/ - _MBG_API_ATTR int _MBG_API mbg_ref_time_accessible( void ) ; +/** + * @brief Error information retrieved from the time adjustment service + */ +typedef struct +{ + uint32_t code; ///< error/status code, see ::ERR_INFO_CODES + FT_DWL_EX time; ///< clock's time and status when ::code was updated - /** - Return the current state of the reference clock. - - @return ::PCPS_TIME_STATUS_X.<br><br> - The status information can be extracted by using the - following bit masks:<br> - <ul><li>::PCPS_FREER</li> - <li>::PCPS_DL_ENB</li> - <li>::PCPS_SYNCD</li> - <li>::PCPS_DL_ANN</li> - <li>::PCPS_UTC</li> - <li>::PCPS_LS_ANN</li> - <li>::PCPS_IFTM</li> - <li>::PCPS_INVT</li> - <li>::PCPS_LS_ENB</li> - <li>::PCPS_ANT_FAIL</li> - <li>::PCPS_UCAP_OVERRUN</li> - <li>::PCPS_UCAP_BUFFER_FULL</li> - <li>::PCPS_IO_BLOCKED</li> - </ul> -*/ - _MBG_API_ATTR int _MBG_API mbg_get_ref_time_status( void ) ; +} ERR_INFO; - /** - Save the latest date and time from a serial time string - plus the associated PC cycles count, so other processes - or functions can use the current cycles count together - with this data pair to interpolate the time between two - time strings. - This function is (and should only be) called by the time - adjustment service. +/** + * @brief Codes used with ::ERR_INFO::code + */ +enum ERR_INFO_CODES +{ + MBG_SVC_NO_ERROR, ///< No current error condition + MBG_SVC_ERR_OPEN_CLOCK_DEV, ///< Failed to open clock device + MBG_SVC_ERR_OPEN_SERIAL_PORT, ///< Failed to open serial port + MBG_SVC_ERR_SAME_REF_TIME, ///< Clock device always returns same time (hardware failure) + MBG_SVC_ERR_REF_TIME_STEP, ///< Time on the clock device has jumped, service stopped disciplining system time + N_MBG_SVC_ERR_CODE ///< the number of known codes +}; - @return MBG_SUCCESS always -*/ - _MBG_API_ATTR int _MBG_API mbg_set_serial_xhrt_data( const REF_TIME_CYCLES *p ) ; - /** - Set the "invalid time" flag (PCPS_INVT) in the status of the - saved serial date and time. This is normally done by time - adjustment service if the serial string times out, e.g. because - the serial device has been disconnected. - @return MBG_SUCCESS always -*/ - _MBG_API_ATTR int _MBG_API mbg_set_serial_xhrt_data_invalid( void ) ; +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ /** - Retrieve the latest date and time from a serial time string - plus the associated PC cycles count, so this data pair can - be used to interpolate the time between two serial strings - using the current cycles count. + * @brief Get the version number of the precompiled DLL/shared object library. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API function are called + * in the correct way. + * + * @return The version number + * + * @see ::mbgsvcio_check_version + * @see ::MBGSVCIO_VERSION defined in mbgsvcio.h. + */ + _MBG_API_ATTR int _MBG_API mbgsvcio_get_version( void ) ; - @return MBG_SUCCESS always -*/ - _MBG_API_ATTR int _MBG_API mbg_get_serial_xhrt_data( uint64_t *tstamp, MBG_XHRT_VARS *vars ) ; + /** + * @brief Check if the DLL/shared library is compatible with a given version. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API functions are called + * in the correct way. + * + * @param[in] header_version Version number to be checked, should be ::MBGSVCIO_VERSION + * from the mbgsvcio.h file version used to build the application + * + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE + * + * @see ::mbgsvcio_get_version + * @see ::MBGSVCIO_VERSION defined in mbgsvcio.h + */ + _MBG_API_ATTR int _MBG_API mbgsvcio_check_version( int header_version ) ; /** - Retrieve a time stamp in PCPS_HR_TIME format which is extrapolated - using the system's current cycles counter value and a time stamp - plus associated cycles counter value from a serial time string, - saved by the time adjustment service. + * @brief Query the status of the Meinberg time adjustment service "mbgadjtm.exe" + * + * @return 1, if the service has the state "SERVICE_RUNNING", otherwise 0. + */ + _MBG_API_ATTR int _MBG_API mbg_time_adjustment_active( void ) ; - @param *p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up. + /** + * @brief Read the ::ERROR_INFO structure from the Meinberg time adjustment service + * + * @param[out] p Pointer to an ::ERROR_INFO structure to be filled on success + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + */ + _MBG_API_ATTR int _MBG_API mbg_get_time_adjustment_err_info( ERR_INFO *p ) ; - @return MBG_SUCCESS + /** + * @brief Check if the reference clock is accessible. + * + * @return 1 if the reference clock is accessible<br> + * 0 if the reference time is invalid (all 0), or the device is inaccessible.<br> + * One of the @ref MBG_ERROR_CODES if the shared memory area is not accessible. + */ + _MBG_API_ATTR int _MBG_API mbg_ref_time_accessible( void ) ; - @see mbg_get_serial_xhrt_time_as_filetime() - */ - _MBG_API_ATTR int _MBG_API mbg_get_serial_xhrt_time_as_pcps_hr_time( PCPS_HR_TIME *p_hrt ) ; + /** + * @brief Read the current refclock's state from the time adjustment service. + * + * This function should be used preferably over ::mbg_get_ref_time_status, + * which is deprecated since the return code from that function can't be + * reliably classified as bit coded clock status code, or error number. + * + * @param[out] p_status Pointer to a ::PCPS_TIME_STATUS_X to be filled on success, or NULL. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::PCPS_TIME_STATUS_X + */ + _MBG_API_ATTR int _MBG_API mbg_get_ref_time_status_ex( PCPS_TIME_STATUS_X *p_status ) ; /** - Retrieve a time stamp in FILETIME format which is extrapolated - using the system's current cycles counter value and a time stamp - plus associated cycles counter value from a serial time string, - saved by the time adjustment service. + * @brief Read the current refclock's state from the time adjustment service. + * + * @deprecated This function is deprecated since its return code can't + * be reliably classified as bit coded clock status code, or error number. + * + * @return A ::PCPS_TIME_STATUS_X status code, or -1 in case of an error. + * + * @see ::mbg_get_ref_time_status_ex + * @see ::PCPS_TIME_STATUS_X + */ + _MBG_API_ATTR int _DEPRECATED_BY( "mbg_get_ref_time_status_ex" ) _MBG_API mbg_get_ref_time_status( void ) ; + +// FIXME +/** + * @brief Save the latest timestamp/cycles pair from a serial device + * + * Save the latest date and time from a serial time string + * plus the associated PC cycles count, so other processes + * or functions can use the current cycles count together + * with this data pair to interpolate the time between two + * time strings. + * + * This function is (and should only be) called by the time + * adjustment service. + * + * @param[in] p The ::FT_DWL_EX_CYCLES info to be saved. + * + * @return Always ::MBG_SUCCESS. + */ + _MBG_API_ATTR int _MBG_API mbg_set_serial_xhrt_data( const FT_DWL_EX_CYCLES *p ) ; - @param *p_ft Pointer to a FILETIME structure to be filled up. +// FIXME +/** + * @brief Set the "invalid time" flag (::PCPS_INVT) in serial date/time status. + * + * The "invalid time" flag (::PCPS_INVT) in the saved serial date and time + * structure is normally set by time adjustment service if the serial string + * times out, e.g. because the serial device has been disconnected or turned off. + * + * @return Always ::MBG_SUCCESS. + */ + _MBG_API_ATTR int _MBG_API mbg_set_serial_xhrt_data_invalid( void ) ; - @return MBG_SUCCESS +// FIXME +/** + * @brief Retrieve the latest timestamp/cycles pair from a serial time string. + * + * Retrieve the latest date and time from a serial time string + * plus the associated PC cycles count, so this data pair can + * be used to interpolate the time between two serial strings + * using the current cycles count. + * + * @param[out] tstamp The interpolated timestamp + * @param[out] vars Pointer to a structure to receive a copy of the ::MBG_XHRT_VARS, or NULL; + * + * @return Always ::MBG_SUCCESS. + */ + _MBG_API_ATTR int _MBG_API mbg_get_serial_xhrt_data( uint64_t *tstamp, MBG_XHRT_VARS *vars ) ; - @see mbg_get_serial_xhrt_time_as_pcps_hr_time() - */ +// FIXME +/** + * @brief Retrieve an extrapolated time stamp in ::PCPS_HR_TIME format. + * + * Retrieve a time stamp in ::PCPS_HR_TIME format which is extrapolated + * using the system's current cycles counter value and a time stamp + * plus associated cycles counter value from a serial time string, + * saved by the time adjustment service. + * + * @param[out] p_hrt Pointer to a ::PCPS_HR_TIME structure to be filled up. + * + * @return The return code from ::mbg_get_serial_xhrt_data, so usually ::MBG_SUCCESS. + * + * @see ::mbg_get_serial_xhrt_time_as_filetime + */ + _MBG_API_ATTR int _MBG_API mbg_get_serial_xhrt_time_as_pcps_hr_time( PCPS_HR_TIME *p_hrt ) ; + +// FIXME +/** + * @brief Retrieve an extrapolated time stamp in FILETIME format. + * + * Retrieve a time stamp in FILETIME format which is extrapolated + * using the system's current cycles counter value and a time stamp + * plus associated cycles counter value from a serial time string, + * saved by the time adjustment service. + * + * @param[out] p_ft Pointer to a FILETIME structure to be filled up. + * + * @return The return code from ::mbg_get_serial_xhrt_data, so usually ::MBG_SUCCESS. + * + * @see ::mbg_get_serial_xhrt_time_as_pcps_hr_time + */ _MBG_API_ATTR int _MBG_API mbg_get_serial_xhrt_time_as_filetime( FILETIME *p_ft ) ; diff --git a/c/mbglib/include/mbgsvctl.h b/c/mbglib/include/mbgsvctl.h deleted file mode 100644 index 5887cee..0000000 --- a/c/mbglib/include/mbgsvctl.h +++ /dev/null @@ -1,263 +0,0 @@ - -/************************************************************************** - * - * $Id: mbgsvctl.h 1.28.1.1 2010/09/16 14:01:24Z martin TRASH $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for servio.c - * - * ----------------------------------------------------------------------- - * $Log: mbgsvctl.h $ - * Revision 1.28.1.1 2010/09/16 14:01:24Z martin - * Branch used to test handle leak under Win Server 2008. - * Revision 1.28 2009/12/15 15:35:09Z daniel - * Revision 1.27.1.1 2009/12/02 13:50:30Z martin - * Revision 1.27 2009/08/14 09:28:41 daniel - * New version code 306, compatibility version code still 214. - * Revision 1.26 2009/06/09 08:57:47Z daniel - * Rev No. 305 - * Revision 1.25 2009/03/19 09:07:26Z daniel - * New version code 304, compatibility version code still 214. - * Revision 1.24 2009/01/28 10:38:15Z daniel - * Added serial flag SERCLOCK_STRING_PER_MINUTE and - * bit mask MSK_SERCLOCK_STRING_PER_MINUTE. - * Revision 1.23 2009/01/12 10:14:23Z daniel - * New version code 303, compatibility version code still 214. - * Changed UINT to uint32_t and LPTSTR to char*. - * Added MBGADJTM_CFG parameters allow_timestep_on_refclk_jump - * and allow_initial_timestep. - * Avoid including mbgdevio.h when MBG_OMIT_MBGDEVIO_H is defined. - * Updated function prototypes. - * Revision 1.22 2008/01/30 07:53:58Z daniel - * New version code 302, compatibility version code still 214. - * Added new members to MBGADJTM_CFG structure to - * support service event handling. - * Revision 1.21 2007/10/16 10:09:51Z daniel - * New file version 3,1,0,0, product version 3,1,0,0. - * New version code 301, compatibility version code still 214. - * Revision 1.20 2007/09/26 14:46:43Z martin - * New version code 300, compatibility version code still 214. - * Identify selected device by hardware ID instead of device index. - * Removed obsolete references to ASCII log file. - * Updated function prototypes. - * Revision 1.19 2007/03/21 16:46:27Z martin - * New version code 219, compatibility version code still 214. - * Changes due to renamed library symbols. - * Updated function prototypes. - * Revision 1.18 2006/10/31 16:24:09Z martin - * Added a serial port flag which prevents the read thread from - * using special timeout settings. - * Revision 1.17 2006/08/09 13:31:11Z martin - * New version code 218, compatibility version code still 214. - * Revision 1.16 2006/06/08 10:36:10Z martin - * New version code 217, compatibility version code still 214. - * Revision 1.15 2006/05/23 19:35:15Z martin - * Updated function prototypes. - * Revision 1.14 2006/05/02 10:08:51Z martin - * New version code 216, compatibility version code still 214. - * Revision 1.13 2006/01/11 11:45:05Z martin - * New version code 215, compatibility version code still 214. - * Revision 1.12 2005/12/15 09:02:05Z martin - * New version 214 and compatibility version 214. - * New service registry parameter "flags" which controls - * logging time adjustment details, and starting paused. - * Updated function prototypes. - * Revision 1.11.1.1 2005/11/28 17:08:34Z martin - * Revision 1.11 2005/07/20 07:23:58Z martin - * New version 213 and compatibility version 213. - * New service cfg parameters notification_limit and - * set_mm_timer. - * Updated function prototypes. - * Revision 1.10 2004/04/27 13:46:40Z martin - * New member flags in MBG_SERCLOCK_CFG. - * Revision 1.9 2004/04/27 07:17:47Z martin - * Changed type of MBG_SERCLOCK_CFG::ref_offs. - * Removed function prototypes that are used in exe-File only - * New definition MBGSVCIO_COMPAT_VERSION. - * Pack structures 1 byte aligned. - * Updated function protoypes. - * Revision 1.8 2003/12/22 15:55:57Z martin - * New DLL interface version number. - * Updated function prototypes. - * Revision 1.7 2003/12/10 10:41:50Z martin - * New DLL interface version number. - * Revision 1.6 2003/10/31 11:11:11Z martin - * New DLL interface version number. - * New structures with config parameters. - * Updated function prototypes. - * Revision 1.5 2003/09/23 09:58:36Z martin - * Updated function prototypes. - * Revision 1.4 2003/04/09 15:24:01Z martin - * Module renamed from servio.h. - * Include standard names and reg paths. - * Updated function prototypes. - * Revision 1.3 2002/09/30 07:54:35Z martin - * Updated function prototypes by MAKEHDR. - * Revision 1.2 2002/02/22 10:35:11Z Daniel - * Revision 1.1 2002/02/18 10:52:18Z Daniel - * Initial revision - * - **************************************************************************/ - -#ifndef _MBGSVCTL_H -#define _MBGSVCTL_H - - -/* Other headers to be included */ - -#if !defined MBG_OMIT_MBGDEVIO_H - #include <mbgdevio.h> -#else - typedef void* MBG_DEVICE_LIST; -#endif - -#include <mbg_tgt.h> -#include <use_pack.h> -#include <gpsdefs.h> - -#if defined( MBG_TGT_WIN32 ) - #include <rs232.h> -#else - #include <mbgserio.h> -#endif - - -#ifdef _MBGSVCTL - #define _ext -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if defined( _USE_PACK ) // set byte alignment - #pragma pack( 1 ) -#endif - - -#define MBGSVCTL_VERSION 0x0307 - -#define MBGSVCTL_COMPAT_VERSION 0x0214 - - -#ifdef __cplusplus -extern "C" { -#endif - - -typedef struct -{ - char hardware_id[256]; - DWORD ignore_sync; - DWORD sync_radius; - DWORD repeat_count; - DWORD max_diff; - DWORD set_local_time; - DWORD gen_statistics; - DWORD notification_limit; - DWORD set_mm_timer; - DWORD evt_handling_enabled; - DWORD async_evt_cmd_delay; - char async_evt_cmd[256]; - char sync_evt_cmd[256]; - DWORD allow_initial_timestep; - DWORD allow_timestep_on_refclk_jump; - DWORD flags; -} MBGADJTM_CFG; - -// Bit masks used with MBGADJTM_CFG::flags: -#define MBGADJTM_CFG_LOG_DETAILS 0x00000001 -#define MBGADJTM_CFG_START_PAUSED 0x00000002 - - - -typedef struct -{ - COMSTRUCT port; - DWORD telegram_type; - DWORD ref_type; - DWORD flags; - MBG_REF_OFFS ref_offs_min; -} MBG_SERCLOCK_CFG; - - -// Bit masks used with MBG_SERCLOCK_CFG::flags: -enum -{ - SERCLOCK_FORCE_UTC, // string contains always UTC time - SERCLOCK_READ_NORMAL, // don't use special timeout settings - SERCLOCK_STRING_PER_MINUTE, // account for serial string once per minute - N_SERCLOCK_FLAGS -}; - -#define MSK_SERCLOCK_FORCE_UTC ( 1UL << SERCLOCK_FORCE_UTC ) -#define MSK_SERCLOCK_READ_NORMAL ( 1UL << SERCLOCK_READ_NORMAL ) -#define MSK_SERCLOCK_STRING_PER_MINUTE ( 1UL << SERCLOCK_STRING_PER_MINUTE ) - - - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - _MBG_API_ATTR int _MBG_API mbgsvctl_get_version( void ) ; - _MBG_API_ATTR int _MBG_API mbgsvctl_check_version( int header_version ) ; - _MBG_API_ATTR void _MBG_API mbgsvctl_log_mbgdevio_error( DWORD ioctl, DWORD rc ) ; - _MBG_API_ATTR int _MBG_API sprint_system_time( char *ws, SYSTEMTIME *st ) ; - _MBG_API_ATTR int _MBG_API mbg_svc_register_event_source( const char *eventlog_name ) ; - _MBG_API_ATTR void _MBG_API mbg_svc_snprint_cfg( char *s, size_t max_len, MBGADJTM_CFG *curr_adjtm_cfg, MBGADJTM_CFG *prev_adjtm_cfg, MBG_SERCLOCK_CFG *curr_serclock_cfg, MBG_SERCLOCK_CFG *prev_serclock_cfg ) ; - _MBG_API_ATTR void _MBG_API mbg_svc_log_msg( DWORD dwIdEvent, DWORD err_code, const char *fmt, const char *info_1, const char *info_2 ) ; - _MBG_API_ATTR BOOL _MBG_API mbg_svc_has_admin_rights( void ) ; - _MBG_API_ATTR void _MBG_API mbg_svc_free_device_list( MBG_DEVICE_LIST *devices ) ; - _MBG_API_ATTR int _MBG_API mbg_svc_find_devices( void ) ; - _MBG_API_ATTR int _MBG_API mbg_svc_find_devices_with_hw_id( MBG_DEVICE_LIST **device_list, int max_devices ) ; - _MBG_API_ATTR const char * _MBG_API mbg_svc_get_device_path( unsigned int device_index ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_mbgadjtm_cfg( const MBGADJTM_CFG *p ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_mbgadjtm_cfg( MBGADJTM_CFG *p ) ; - _MBG_API_ATTR void _MBG_API mbg_svc_get_mbgadjtm_cfg_default( MBGADJTM_CFG *p ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_mbg_serclock_cfg( const MBG_SERCLOCK_CFG *p ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_mbg_serclock_cfg( MBG_SERCLOCK_CFG *p ) ; - _MBG_API_ATTR void _MBG_API mbg_svc_get_mbg_serclock_cfg_default( MBG_SERCLOCK_CFG *p ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_msgs_filename( char *s, size_t size ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_stats_filename( char *s, size_t size ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_adjtm_filename( char *s, size_t size ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_query_status( const char *svc_name ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_start( const char *svc_name ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_stop( const char *svc_name ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_pause( const char *svc_name ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_continue( const char *svc_name ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_install( const char *svc_name, DWORD svc_type, DWORD svc_start_type, const char *svc_disp_name, const char *svc_description, const char *svc_exe_path, const char *svc_dependencies ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_remove( const char *svc_name ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_autostart( const char *svc_name, BOOL autostart ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_description( const char *svc_name, const char *descr ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_set_ctry_code( const DWORD *p ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_ctry_code( DWORD *p ) ; - _MBG_API_ATTR void _MBG_API mbg_svc_get_ctry_code_default( DWORD *p ) ; - _MBG_API_ATTR const char * _MBG_API mbg_svc_name_time_adjustment( void ) ; - _MBG_API_ATTR const char * _MBG_API mbg_svc_name_clock_kernel_driver( void ) ; - _MBG_API_ATTR const char * _MBG_API mbg_svc_name_ntp( void ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_get_exe_path( char* svc_exe_path, uint32_t svc_exe_path_max_len, const char *svc_exe_name, const char *subdir ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_install_time_adjustment( void ) ; - _MBG_API_ATTR DWORD _MBG_API mbg_svc_uninstall_time_adjustment( void ) ; - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - - -#if defined( _USE_PACK ) // set default alignment - #pragma pack() -#endif - -/* End of header body */ - -#undef _ext - -#endif // _MBGSVCTL_H - diff --git a/c/mbglib/include/mbgsystm.h b/c/mbglib/include/mbgsystm.h new file mode 100644 index 0000000..44ece8e --- /dev/null +++ b/c/mbglib/include/mbgsystm.h @@ -0,0 +1,494 @@ + +/************************************************************************** + * + * $Id: mbgsystm.h 1.5 2019/02/08 11:05:48Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Generic functions and definitions to deal with the computer's + * system time, and prototypes for mbgsystm.c. + * + * ----------------------------------------------------------------------- + * $Log: mbgsystm.h $ + * Revision 1.5 2019/02/08 11:05:48Z martin + * Commonly use int64_t for MBG_SYS_TIME on Windows, rather than + * FILETIME in user space and LARGE_INTEGER in kernel space. + * Also use a function pointer to read the Windows system time + * depending on whether the precise time API calls are supported + * by the running Windows system, or not. + * Revision 1.4 2018/07/16 12:32:58 martin + * Fixed do_div() for 32 bit ARM Linux kernel. + * Include another header file on NetBSD. + * Revision 1.3 2017/07/26 14:26:17 martin + * Fixed build for NetBSD. + * Revision 1.2 2017/07/04 12:26:57 martin + * More detailed control of inclusion of other headers. + * Made mbg_delta_sys_time_ms() as inline function here. + * Updated function prototypes. + * Cleanup. + * Revision 1.1 2015/09/15 13:21:00Z martin + * Initial revision. + * Moved existing code from different modules here. + * + **************************************************************************/ + +#ifndef _MBGSYSTM_H +#define _MBGSYSTM_H + + +/* Other headers to be included */ + +#include <mbg_tgt.h> +#include <words.h> + +#if defined( MBG_TGT_POSIX ) + + #if defined( MBG_TGT_KERNEL ) + + #if defined( MBG_TGT_LINUX ) + + #define LINUX_KERNEL_HAS_MSLEEP ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 16 ) ) + #define LINUX_KERNEL_HAS_GETNSTIMEOFDAY ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 22 ) ) + #define LINUX_KERNEL_HAS_KTIME_H ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 16 ) ) + + #if !LINUX_KERNEL_HAS_MSLEEP + #include <linux/wait.h> + #include <linux/sched.h> + #endif + + // We need the prototype for getnstimeofday(). In newer kernels + // (e.g. 4.x) this is available via linux/ktime.h, which in turn + // includes linux/timekeeping.h, which declares the prototype. + #if LINUX_KERNEL_HAS_KTIME_H + #include <linux/ktime.h> + #endif + + // In older kernel versions the prototype for getnstimeofday() + // is declared in linux/time.h, so we include that one anyway. + #include <linux/time.h> + + #include <linux/delay.h> + #include <linux/jiffies.h> + + #elif defined( MBG_TGT_BSD ) + + #if defined( MBG_TGT_FREEBSD ) + #include <sys/libkern.h> + #endif + + #if defined( MBG_TGT_NETBSD ) + #include <sys/param.h> // mstohz + #include <sys/kernel.h> // hz + #include <sys/proc.h> // kpause + #endif + + #include <sys/time.h> + + #endif + + #else // POSIX user space + + #include <time.h> + + #if defined( MBG_TGT_LINUX ) + #include <sys/sysinfo.h> + #endif + + #endif + +#elif defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) + #include <mbg_w32.h> // ke_query_system_time_fnc + #else + #include <timeutil.h> // gstaft_fnc + #endif + + #include <mbgtime.h> + +#elif defined( MBG_TGT_DOS ) + + #include <dos.h> + +#endif + + +#ifdef _MBGSYSTM + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +/* + * Generic types to hold system timestamps and values for the system uptime.. + */ +#if defined( MBG_TGT_POSIX ) + + typedef NANO_TIME_64 MBG_SYS_TIME; + typedef int64_t MBG_SYS_UPTIME; // [s] + +#elif defined( MBG_TGT_WIN32 ) + + typedef int64_t MBG_SYS_TIME; // Number of 100ns units + typedef int64_t MBG_SYS_UPTIME; // [s] + +#elif defined( MBG_TGT_OS2 ) + + typedef uint32_t MBG_SYS_TIME; //## dummy + typedef long MBG_SYS_UPTIME; //## dummy + +#elif defined( MBG_TGT_DOS ) + + typedef uint32_t MBG_SYS_TIME; //## dummy + typedef long MBG_SYS_UPTIME; //## dummy + +#else // other target OSs which access the hardware directly + + typedef uint32_t MBG_SYS_TIME; //## dummy + typedef long MBG_SYS_UPTIME; //## dummy + +#endif + +//### TODO +// MBG_SYS_TIME is always read in native machine endianess, +// so no need to convert endianess. +#define _mbg_swab_mbg_sys_time( _p ) \ + _nop_macro_fnc() + + + +static __mbg_inline +void mbg_get_sys_time( MBG_SYS_TIME *p ) +{ + #if defined( MBG_TGT_POSIX ) + + #if defined( MBG_TGT_KERNEL ) // kernel space functions even differ for POSIX systems + + #if defined( MBG_TGT_LINUX ) // Linux kernel space + + #if ( LINUX_KERNEL_HAS_GETNSTIMEOFDAY ) + { + // getnstimeofday() supported + struct timespec ts; + + getnstimeofday( &ts ); + + p->secs = ts.tv_sec; + p->nano_secs = ts.tv_nsec; + } + #else + { + // getnstimeofday() *not* supported + struct timeval tv; + + do_gettimeofday( &tv ); + + p->secs = tv.tv_sec; + p->nano_secs = tv.tv_usec * 1000; + } + #endif + + #elif defined( MBG_TGT_BSD ) // BSD kernel space + { + struct timespec ts; + + nanotime( &ts ); + + p->secs = ts.tv_sec; + p->nano_secs = ts.tv_nsec; + } + #endif + + #else // POSIX user space + { + struct timespec ts; + + #if defined( CLOCK_REALTIME_PRECISE ) // at least available in FreeBSD + clock_gettime( CLOCK_REALTIME_PRECISE, &ts ); + #else + clock_gettime( CLOCK_REALTIME, &ts ); + #endif + + p->secs = ts.tv_sec; + p->nano_secs = ts.tv_nsec; + } + #endif + + #elif defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) // Windows kernel space + ke_query_system_time_fnc( (LARGE_INTEGER *) p ); + #else // Windows user space + { + gstaft_fnc( (FILETIME *) p ); + } + #endif + + #else + + *p = 0; // dummy + + #endif + +} // mbg_get_sys_time + + + +static __mbg_inline +void mbg_get_sys_uptime( MBG_SYS_UPTIME *p ) +{ + #if defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) // kernel space + + ULONGLONG time_increment = KeQueryTimeIncrement(); + LARGE_INTEGER tick_count; + + KeQueryTickCount( &tick_count ); + + // multiplication by time_increment yields HNS units, + // but we need seconds + *p = ( tick_count.QuadPart * time_increment ) / HNS_PER_SEC; + + #else // user space + + DWORD tickCount; + DWORD timeAdjustment; + DWORD timeIncrement; + BOOL timeAdjustmentDisabled; + + if ( !GetSystemTimeAdjustment( &timeAdjustment, &timeIncrement, &timeAdjustmentDisabled ) ) + *p = -1; // failed + + // ATTENTION: This is compatible with older Windows versions, but + // the returned tick count wraps around to zero after 49.7 days. + // A new GetTickCount64() call is available under Windows Vista and newer, + // but the function call had to be imported dynamically since otherwise + // programs refused to start under pre-Vista versions due to undefined DLL symbol. + tickCount = GetTickCount(); + + *p = ( ( (MBG_SYS_UPTIME) tickCount ) * timeIncrement ) / HNS_PER_SEC; + + #endif + + #elif defined( MBG_TGT_LINUX ) + + #if defined( MBG_TGT_KERNEL ) + // getrawmonotonic() can possibly be used for this in newer kernels + { + // Using a simple 64 bit division may result in a linker error + // in kernel mode due to a missing symbol __udivdi3, so we use + // a specific inline function do_div(). + // Also, the jiffies counter is not set to 0 at startup but to + // a defined initialization value we need to account for. + uint64_t tmp = get_jiffies_64() - INITIAL_JIFFIES; + do_div( tmp, HZ ); + *p = tmp; + } + #else + { + struct sysinfo si; + int rc = sysinfo( &si ); + *p = ( rc == 0 ) ? si.uptime : -1; + } + #endif + + #elif defined( MBG_TGT_BSD ) + + #if defined( MBG_TGT_KERNEL ) + { + struct timespec ts; + #if 0 //##+++++++ + { + struct bintime bt; + + binuptime( &bt ); + #if defined( DEBUG ) + printf( "binuptime: %lli.%09lli\n", + (long long) bt.sec, + (long long) bt.frac ); + #endif + } + #endif + + nanouptime( &ts ); + #if defined( DEBUG ) + printf( "nanouptime: %lli.%09lli\n", + (long long) ts.tv_sec, + (long long) ts.tv_nsec ); + #endif + *p = ts.tv_sec; + } + #elif defined( MBG_TGT_FREEBSD ) + { + struct timespec ts; + // CLOCK_UPTIME_FAST is specific to FreeBSD + int rc = clock_gettime( CLOCK_UPTIME_FAST, &ts ); + *p = ( rc == 0 ) ? ts.tv_sec : -1; + } + #else // MBG_TGT_NETBSD, ... + + *p = -1; //##++ needs to be implemented + + #endif + + #else + + *p = -1; // not supported + + #endif + +} // mbg_get_sys_uptime + + + +/** + * @brief Compute delta between two ::MBG_SYS_TIME times, in milliseconds + * + * @param[in] t2 the time to be subtracted from + * @param[in] t1 The time to be subtracted + * + * @return The time difference in [milliseconds] + */ +static __mbg_inline +long mbg_delta_sys_time_ms( const MBG_SYS_TIME *t2, const MBG_SYS_TIME *t1 ) +{ + #if defined( MBG_TGT_POSIX ) + long dt = ( t2->secs - t1->secs ) * 1000; + #if defined ( MBG_TGT_LINUX ) && defined( MBG_TGT_KERNEL ) + uint64_t tmp64 = t2->nano_secs - t1->nano_secs; + do_div( tmp64, 1000000 ); + dt += tmp64; + #else + dt += ( t2->nano_secs - t1->nano_secs ) / 1000000; + #endif + return dt; + #elif defined( MBG_TGT_WIN32 ) + return (long) ( ( *t2 - *t1 ) / HNS_PER_MS ); + #else + return 0; + #endif + +} // mbg_delta_sys_time_ms + + + +static __mbg_inline +void mbg_sleep_sec( long sec ) +{ + #if defined( MBG_TGT_POSIX ) + + #if defined( MBG_TGT_KERNEL ) // kernel space functions even differ for POSIX systems + + #if defined( MBG_TGT_LINUX ) // Linux kernel space + + // msleep is not defined in older kernels, so we use this + // only if it is surely supported. + #if LINUX_KERNEL_HAS_MSLEEP + msleep( sec * 1000 ); + #else + { + DECLARE_WAIT_QUEUE_HEAD( tmp_wait ); + wait_event_interruptible_timeout( tmp_wait, 0, sec * HZ + 1 ); + } + #endif + + #elif defined( MBG_TGT_FREEBSD ) + + struct timeval tv = { 0 }; + int ticks; + tv.tv_sec = sec; + ticks = tvtohz( &tv ); + + #if defined( DEBUG ) + printf( "pause: %lli.%06lli (%i ticks)\n", + (long long) tv.tv_sec, + (long long) tv.tv_usec, + ticks ); + #endif + + pause( "pause", ticks ); + + #elif defined( MBG_TGT_NETBSD ) + + int timeo = mstohz( sec * 1000 ); + + #if defined( DEBUG ) + printf( "kpause: %i s (%i ticks)\n", sec, timeo ); + #endif + + kpause( "pause", 1, timeo, NULL ); + + #endif + + #else // POSIX user space + + sleep( sec ); + + #endif + + #elif defined( MBG_TGT_WIN32 ) + + #if defined( MBG_TGT_KERNEL ) // kernel space + + LARGE_INTEGER delay; + + // we need to pass a negative value to KeDelayExecutionThread() + // since the given time is a relative time interval, not absolute + // time. See the API docs for KeDelayExecutionThread(). + delay.QuadPart = - ((LONGLONG) sec * HNS_PER_SEC); + + KeDelayExecutionThread( KernelMode, FALSE, &delay ); + + #else // user space + + // Sleep() expects milliseconds + Sleep( sec * 1000 ); + + #endif + + #elif defined( MBG_TGT_DOS ) + + delay( (unsigned) ( sec * 1000 ) ); + + #else + + // This needs to be implemented for the target OS + // and thus will probably yield a linker error. + do_sleep_sec( sec ); + + #endif + +} // mbg_sleep_sec + + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + +/* (no header definitions found) */ + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _MBGSYSTM_H */ diff --git a/c/mbglib/include/mbgtime.h b/c/mbglib/include/mbgtime.h index c7b0eee..1927352 100644 --- a/c/mbglib/include/mbgtime.h +++ b/c/mbglib/include/mbgtime.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgtime.h 1.20 2014/05/27 08:09:19Z martin REL_M $ + * $Id: mbgtime.h 1.38 2019/09/27 14:53:20Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,63 @@ * * ----------------------------------------------------------------------- * $Log: mbgtime.h $ - * Revision 1.20 2014/05/27 08:09:19Z martin + * Revision 1.38 2019/09/27 14:53:20Z martin + * New define MONTHS_PER_YEAR. + * New types MBG_TIME32_T MBG_TIME32U_T. + * New inline function mbg_exp_year(). + * New inline functions normalize_gps_wn_dn() and de_normalize_gps_wn_dn(). + * New definitions for different types of leap second tables. + * New function is_valid_leap_second_date() and variants thereof. + * Updated function prototypes. + * Revision 1.37 2019/08/28 13:19:40 martin + * New structures MBG_TZ_INFO and MBG_LS_INFO which + * are used by some new functions in new module mbgtimex.c. + * Revision 1.36 2019/08/02 07:51:30 martin + * New type MBG_TIME64_T. + * Revision 1.35 2019/07/23 07:27:37 martin + * Added definition GPS_INITIAL_DAY. + * Revision 1.34 2019/07/19 08:39:19 martin + * Don't mark frac_sec_from_bin() as deprecated anymore. + * Revision 1.33 2019/07/19 07:49:22Z martin + * Modified dec_frac_to_bin_frac_{16,32} so that no compiler + * warning is emitted if a large data type is passed as an argument. + * Revision 1.32 2019/06/26 10:03:02Z martin + * Updated function prototypes. + * Revision 1.31 2019/02/06 10:08:09 martin + * Added symbol HNS_PER_MIN. + * Revision 1.30 2018/11/26 12:04:44Z martin + * Moved definition NTP_FRAC_PER_SEC here. + * Revision 1.29 2018/02/28 16:58:10 martin + * Removed reference to frac_sec_from_bin(). + * Revision 1.28 2018/01/15 18:18:49 martin + * Renamed symbol NSECS_PER_SEC to NSEC_PER_SEC. + * according to namings of similar symbols. + * Revision 1.27 2017/11/29 11:14:57 gregoire + * Added Multiplier MSEC_TO_NSEC_MULTIPLIER, MSEC_TO_USEC_MULTIPLIER. + * Revision 1.26 2017/11/16 13:33:46 philipp + * Added USEC_PER_SEC define. + * Revision 1.25 2017/08/15 15:48:59 martin + * Define NSECS_PER_SEC only if it hasn't been defined before. + * Revision 1.24 2017/07/04 14:02:25 martin + * Made definitions of some constants signed to avoid + * signed/unsigned compiler warnings. + * Moved some macros and inline functions for fraction + * conversion here. They are excluded from build in kernel + * mode, though, since some kernels don't support this properly. + * Moved some NANO_TIME- and NANO_TIME_64-related inline + * functions to new module nanotime.c. + * Renamed PCPS_HRT_BIN_FRAC_SCALE to MBG_FRAC32_UNITS_PER_SEC. + * Updated function prototypes. + * Doxygen stuff. + * Revision 1.23 2017/03/16 12:26:13 martin + * Updated function prototypes. + * Revision 1.22 2017/01/25 13:10:55 gregoire.diehl + * nano_time_64_to_double and double_to_nano_time_64 added + * Revision 1.21 2016/12/15 17:44:59Z martin + * Changed conditions to include time.h. + * Fixed spelling. + * Removed trailing spaces. + * Revision 1.20 2014/05/27 08:09:19 martin * Added NTP_SEC_BIAS. * Revision 1.19 2013/05/22 16:47:01 martin * Added some useful macros. @@ -63,10 +119,7 @@ #include <gpsdefs.h> -#if _IS_MBG_FIRMWARE \ - || defined( MBG_TGT_WIN32 ) \ - || defined( MBG_TGT_DOS ) \ - || defined( MBG_TGT_QNX_NTO ) +#if !defined( MBG_TGT_KERNEL ) || defined( MBG_TGT_WIN32 ) #include <time.h> #endif @@ -77,6 +130,7 @@ extern "C" { #ifdef _MBGTIME #define _ext + #define _DO_INIT #else #define _ext extern #endif @@ -84,6 +138,158 @@ extern "C" { /* Start of header body */ +/** + * @defgroup leap_second_fncs Meinberg leap second support functions + * + * By default, the date and time ***at the end of a leap second*** + * is referred to as <em>leap second date</em>. This is because: + * + * - At this point in time a new TAI offset comes into effect. + * + * - This is precise both in case of an inserted leap second (when the + * numbered seconds are counted 59, 60, 0) as well as for a deleted + * leap second (when the numbered seconds jump from 58 to 0, and + * there is no second numbered 59). + * + * - This complies with the leap second tables published by the + * International Earth Rotation and Reference Systems Service (IERS). + * + * So, for example, instead of 2016-12-31 23:59:59 we expect + * 2017-01-01 00:00:00 as a valid leap second date. + */ + +/** + * @defgroup leap_date_valid_fncs Meinberg functions that check if a leap second date is valid + * @ingroup leap_second_fncs + * + * For detailed hints, see @ref leap_second_fncs. + * + * Actually, only dates at the beginning of January or or July are + * considered valid leap second dates. There are several functions: + * + * @see ::is_valid_leap_second_date_tm A check function that expects a <em>struct tm</em> parameter. + * @see ::is_valid_leap_second_date_tm_gps A check function that expects a ::TM_GPS parameter. + * @see ::is_valid_leap_second_date A generic check function that expects day of month and month. + * + * @see @ref leap_second_fncs + */ + +/** + * @defgroup group_true_gps_wn_fncs Functions to determine a true leap second week number + * @ingroup leap_second_fncs + * + * The ::UTC::WNlsf field originally transmitted by the GPS satellites + * contains only the 8 LSBs of the full leap second week number, covering + * only a range of +/- ~128 weeks from the current week number. + * + * GPS receivers try to derive a full extended week number + * from this truncated week number. + * + * If the %UTC offset fields ::UTC::delta_tls and ::UTC::delta_tlsf + * are different, this means that a leap second is currently being + * announced, and thus the leap second week number is indeed in + * the range of +/- ~128 week of the current week, which means + * the week number can be unambiguously extended by the receiver. + * + * However, if ::UTC::delta_tls and ::UTC::delta_tlsf are the + * same, no leap second is announced, and it's not clear in + * which 256-week cycle the last leap second really occurred. + * These functions can be used to try to resolve this ambiguity, + * and, if possible, determine the true extended week number. + * + * The approach implemented here is based on a suggestion by + * Tom van Baak [[tvb@leapsecond.com]] on the leap seconds mailing + * list, and the fact that previous leap seconds were inserted only + * at the end of June/beginning of July, or end of December/beginning + * of January, and there are no plans to change this in the foreseeable + * future. + * + * The truncated week number is expanded for subsequent 256-week + * cycles, and if the extended week number and given day number + * yield a date that matches one of these well-known leap second + * dates then we have found the correct extended week number. + * + * A test has shown that there are unique results for 25 256-week + * cycles from 1980, i.e. until year 2099, if only leap seconds + * at the beginning of January or July are accepted. If the number of + * 256-week cycles is extended beyond 25 / year 2099, or if leap + * dates at the beginning of April or october are in addition taken + * into account then the results can be ambiguous, i.e. there + * can be more than one match. + * + * For example, both week numbers 1929 (0x0789, real week number) + * and 2185 (0x0889, off by 256 weeks) with correct day 7 yield + * the real leap second date 2017-01-01. + * + * @see ::mbg_find_true_gps_wn_lsf + * @see ::mbg_find_true_gps_wn_lsf_ex + * @see ::find_past_gps_wn_lsf_from_table + */ + + + +/** + * @defgroup group_timestamp_types Data types to store timestamps. + * + * Depending on the build and target environment, the original + * POSIX @a time_t type is usually 32 bits or 64 bits wide. + * If it is only 32 bits wide, timestamps will overflow in 2038. + * + * Using 64 bit types and associated time conversion functions + * avoid a rollover in 2038. + * + * Using a distinct 32 bit type can be useful for API calls which + * return 32 bit timestamps only, which may need to be mapped to + * an extended 64 bit range. + */ + +/** + * @brief A POSIX-like timestamp, 64 bits wide, signed. + * + * Negative numbers can represent times before the epoch. + * + * @ingroup group_timestamp_types + * @see @ref group_timestamp_types + */ +typedef int64_t MBG_TIME64_T; + + +/** + * @brief A POSIX-like timestamp, 32 bits wide, signed. + * + * Negative numbers can represent times before the epoch, + * but rolls over earlier than the unsigned type ::MBG_TIME32U_T. + * + * @ingroup group_timestamp_types + * @see @ref group_timestamp_types + */ +typedef int32_t MBG_TIME32_T; + + +/** + * @brief A POSIX-like timestamp, 32 bits wide, unsigned. + * + * No negative numbers, so times before the epoch + * can't be represented, but rolls over later + * than the signed type ::MBG_TIME32_T. + * + * @ingroup group_timestamp_types + * @see @ref group_timestamp_types + */ +typedef uint32_t MBG_TIME32U_T; + + + +/** + * @brief The number of days from 0000-01-01 until GPS epoch + * + * The number of days as computed by ::n_days for the date + * of the GPS epoch, 1980-01-06. + * + * @see ::n_days + */ +#define GPS_INITIAL_DAY 722819L + /** * @brief GPS epoch bias from ordinary time_t epoch @@ -109,6 +315,10 @@ extern "C" { */ #define NTP_SEC_BIAS 2208988800UL +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + #define NTP_FRAC_PER_SEC (uint64_t) 4294967296.0 +#endif + // Modified Julian Day (MJD) numbers for some commonly used epochs. @@ -121,7 +331,7 @@ extern "C" { // The constant below defines the Windows FILETIME number (100 ns intervals -// since 1601-01-01) for 1970-01-01, which is usually the epoche for the time_t +// since 1601-01-01) for 1970-01-01, which is usually the epoch for the time_t // type used by the standard C library. #if !defined( FILETIME_1970 ) // FILETIME represents a 64 bit number, so we need to defined the @@ -190,8 +400,10 @@ typedef struct clock_t start; clock_t stop; short is_set; + } TIMEOUT; +#define MONTHS_PER_YEAR 12 #define DAYS_PER_WEEK 7 @@ -212,23 +424,36 @@ typedef struct #define SEC100S_PER_DAY ( SEC100S_PER_SEC * SECS_PER_DAY ) #if !defined( MSEC_PER_SEC ) - #define MSEC_PER_SEC 1000L + #define MSEC_PER_SEC 1000L #endif -#define MSEC_PER_MIN ( MSEC_PER_SEC * SECS_PER_MIN ) -#define MSEC_PER_HOUR ( MSEC_PER_SEC * SECS_PER_HOUR ) -#define MSEC_PER_DAY ( MSEC_PER_SEC * SECS_PER_DAY ) +#define MSEC_PER_MIN ( MSEC_PER_SEC * SECS_PER_MIN ) +#define MSEC_PER_HOUR ( MSEC_PER_SEC * SECS_PER_HOUR ) +#define MSEC_PER_DAY ( MSEC_PER_SEC * SECS_PER_DAY ) -#define NSECS_PER_SEC 1000000000UL +#if !defined( USEC_PER_SEC ) + #define USEC_PER_SEC 1000000L +#endif + +#if !defined( NSEC_PER_SEC ) + #define NSEC_PER_SEC 1000000000L +#endif #if !defined( HNS_PER_SEC ) - #define HNS_PER_SEC 10000000UL + #define HNS_PER_SEC 10000000L #endif #if !defined( HNS_PER_MS ) - #define HNS_PER_MS 10000UL + #define HNS_PER_MS 10000L +#endif + +#if !defined( HNS_PER_MIN ) + #define HNS_PER_MIN ( HNS_PER_SEC * SECS_PER_MIN ) #endif +#define MSEC_TO_NSEC_MULTIPLIER ( NSEC_PER_SEC / MSEC_PER_SEC ) +#define MSEC_TO_USEC_MULTIPLIER ( USEC_PER_SEC / MSEC_PER_SEC ) + /** * @brief A table with the days of month @@ -258,56 +483,56 @@ _ext TM_GPS datum; _ext const char *short_time_fmt -#ifdef _MBGTIME +#ifdef _DO_INIT = "%2i:%02i" #endif ; _ext const char *time_fmt -#ifdef _MBGTIME +#ifdef _DO_INIT = "%2i:%02i:%02i" #endif ; _ext const char *long_time_fmt -#ifdef _MBGTIME +#ifdef _DO_INIT = "%2i:%02i:%02i.%02i" #endif ; _ext const char *date_fmt -#ifdef _MBGTIME +#ifdef _DO_INIT = "%2i.%02i.%04i" #endif ; _ext const char *day_date_fmt -#ifdef _MBGTIME +#ifdef _DO_INIT = "%s, %2i.%02i.%04i" #endif ; _ext const char *day_name_eng[] -#ifdef _MBGTIME +#ifdef _DO_INIT = { "Su", "Mo", "Tu", "We", "Th", "Fr", "Sa" } #endif ; _ext const char *day_name_ger[] -#ifdef _MBGTIME +#ifdef _DO_INIT = { "So", "Mo", "Di", "Mi", "Do", "Fr", "Sa" } #endif ; _ext const TM_GPS init_tm -#ifdef _MBGTIME +#ifdef _DO_INIT = { 1980, 1, 1, 0, 0, 0, 0, 0, 0, 0 } #endif ; _ext DAYS_OF_MONTH_TABLE days_of_month -#ifdef _MBGTIME +#ifdef _DO_INIT = DAYS_OF_MONTH_TABLE_INIT #endif ; @@ -327,34 +552,938 @@ _ext DAYS_OF_MONTH_TABLE days_of_month +static __mbg_inline /*HDR*/ +/** + * @brief Expand a 2-digit year-of-the-century to a full 4-digit year number. + * + * The resulting year number includes the century and is + * in the range [year_lim ... ( year_lim + 99 )]. + * + * @param[in] year The 2-digit year-of-the-century to be converted. + * + * @param[in] year_lim The smallest 4-digit year number to be returned. + * + * @return The resulting 4 digit year number including century. + */ +int mbg_exp_year( int year, int year_lim ) +{ + int lyear = year + year_lim - ( year_lim % 100 ); + + if ( lyear < year_lim ) + lyear += 100; + + return lyear; + +} // mbg_exp_year + + + +static __mbg_inline /*HDR*/ +/** + * @brief Normalize a GPS week number / day number pair. + * + * GPS navigation data may contain week number / day number pairs where + * the day number is in the range 1..7 rather than 0..6. For example, + * a known leap second date was sent with 1929|7 instead of 1930|0. + * + * To resolve this ambiguity in computations, this function can be used + * to normalize the wn|dn pair. + * + * The complementary function ::de_normalize_gps_wn_dn can be used + * to convert a wn|dn pair back to the common wn|dn format where the + * day number is in the range 1..7. + * + * @param[in,out] p_wn Address of a variable containing the week number. + * @param[in,out] p_dn Address of a variable containing the day number. + * + * @see ::de_normalize_gps_wn_dn + */ +void normalize_gps_wn_dn( GPS_WNUM *p_wn, GPS_DNUM *p_dn ) +{ + if ( *p_dn == 7 ) + { + *p_dn = 0; + (*p_wn)++; + } + +} // normalize_gps_wn_dn + + + +static __mbg_inline /*HDR*/ +/** + * @brief De-normalize a GPS week number / day number pair. + * + * GPS navigation data may contain week number / day number pairs where + * the day number is in the range 1..7 rather than 0..6. For example, + * a known leap second date was sent with 1929|7 instead of 1930|0. + * + * However, the function ::normalize_gps_wn_dn may have been called before + * to normalize the wn|dn pair to simplify computations. + * + * This function can be used to convert a wn|dn pair back to the common + * wn|dn format where the day number is in the range 1..7. + * + * @param[in,out] p_wn Address of a variable containing the week number. + * @param[in,out] p_dn Address of a variable containing the day number. + * + * @see ::normalize_gps_wn_dn + */ +void de_normalize_gps_wn_dn( GPS_WNUM *p_wn, GPS_DNUM *p_dn ) +{ + if ( *p_dn == 0 ) + { + *p_dn = 7; + (*p_wn)--; + } + +} // de_normalize_gps_wn_dn + + + +#if !defined( MBG_TGT_KERNEL ) + +/** + * @brief Data type used for intermediate results on 32 bit multiplications + * + * We need 64 bits for intermediate integer results to avoid a range overflow + * from 32 x 32 bit multiplications. On systems which don't support 64 bit types + * we use the "double" type as a workaround. + */ +#if defined( MBG_TGT_MISSING_64_BIT_TYPES ) + #define MBG_FRAC32_CONVERSION_TYPE double +#else + #define MBG_FRAC32_CONVERSION_TYPE int64_t +#endif + +/** + * @brief Constant used to convert e.g. ::PCPS_TIME_STAMP::frac values + * + * Max value of ::PCPS_TIME_STAMP::frac + 1, used for scaling + */ +#define MBG_FRAC32_UNITS_PER_SEC ( (MBG_FRAC32_CONVERSION_TYPE) 4294967296.0 ) // == 0x100000000 + + + +/** + * @brief DST on/off times pre-computed for a given year. + * + * Used like a cache to avoid redundant expensive computation + * of DST switching times for a given year inside an application. + * Not to be used for data exchange between devices. + * + * By default, switching times @a #t_on and @a #t_off are stored + * as local standard time (i.e. %UTC + @a #offs already applied) + * because this is most suitable for %UTC to local time conversions. + * + * However, for some cases (e.g. with PTP SMPTE) the switching + * times need to be compared to TAI times, so the function + * ::mbg_tz_info_to_tai can be used to convert the switching + * times to TAI. Care must be taken that the TAI switching times + * also need to be updated whenever a leap second event occurrs. + * + * @see ::mbg_set_tz_info_for_year + * @see ::mbg_set_tz_info_for_utc_time64_t + * @see ::mbg_tz_info_to_tai + */ +typedef struct +{ + MBG_TIME64_T t_on; ///< 'DST on' time, local standard time (default), or TAI. + MBG_TIME64_T t_off; ///< 'DST off' time, local standard time (default), or TAI. + int offs; ///< Offset to be added to %UTC to yield local standard time [sec]. + int offs_dl; ///< Additional offset to be added if daylight saving is in effect [sec]. + int year; ///< The year number for which @a #t_on and @a #t_off have been computed. + int auto_flag; ///< A flag indicating that @a #t_on and @a #t_off were computed by automatic rules. + int valid; ///< A flag indicating that the information in this structure has been set up. + +} MBG_TZ_INFO; + + + +/** + * @brief Current %UTC/TAI Offset And Leap Second Information. + * + * The stored information can be retrieved e.g. from the + * ::UTC data set transmitted by the GPS satellites, + * or from an NTP leap second file. + * + * @see ::mbg_set_ls_info_from_gps_utc + */ +typedef struct +{ + /// @brief Time of the nearest leap second, if available, in %UTC time scale. + /// Should match %UTC midnight at the end of the last day in June or December of a given year. + MBG_TIME64_T t64_ls_utc; + + /// @brief Time of the nearest leap second, if available, in TAI time scale. + /// Should be ahead of @a #t64_ls_utc by a number of leap seconds (~37 s in year 2019) + /// that have already been inserted in the past. + MBG_TIME64_T t64_ls_tai; + + /// @brief Number of seconds to be inserted into the %UTC time scale at the leap second transition. + /// This is 0 as long as no leap second announcement is currently available, +1 for a leap + /// second to be inserted, and -1 for a leap second to be deleted, which has yet never happened. + int ls_step; + + int offs_gps_utc; ///< Number of seconds the GPS system time is ahead of %UTC after the leap second transition. + + int offs_tai_utc; ///< Number of seconds TAI is ahead of %UTC after the leap second transition. + + int valid; ///< Indicates that the structure has been set up. + +} MBG_LS_INFO; + + + +/** + * @brief Entry of a leap second table providing timestamps and %UTC/TAI offsets. + * + * There are initializers that can be used to instantiate a table of entries. + * + * @see ::KNOWN_LEAP_SECOND_INFO_NTP + * @see ::KNOWN_LEAP_SECOND_INFO_POSIX + * @see ::LS_TABLE_ENTRY_GPS + */ +typedef struct +{ + /// Timestamp associated with ***the end*** of the leap second, + /// e.g. 2017-01-01 00:00:00 instead of 2016-12-31 23:59:59. + MBG_TIME64_T t_ls; + + /// Number of seconds that %UTC is ***behind*** TAI + /// after the given time. + int utc_tai_offs; + +} LS_TABLE_ENTRY; + + + +/** + * @brief Entry of a leap second table providing GPS timestamps and %UTC/GPS offsets. + * + * There is an initializer that can be used to instantiate a table of entries. + * + * ***Please note*** the table contains normalized wn|dn pairs like 1930|0, + * while the ::UTC info sent by the satellites could be 1929|7. So the wn|dn + * pairs from a GPS receiver should be normalized before being compared. + * + * @see ::KNOWN_LEAP_SECOND_INFO_GPS + * @see ::LS_TABLE_ENTRY + */ +typedef struct +{ + /// Extended GPS week number during which a leap second occurs. + GPS_WNUM wn; + + /// A day-of-week indicating when the leap second occurs. + /// Associated with ***the end*** of the leap second, + /// e.g. 2017-01-01 00:00:00 instead of 2016-12-31 23:59:59. + GPS_DNUM dn; + + /// Number of seconds that %UTC is ***behind*** GPS + /// after the given time. + int gps_tai_offs; + +} LS_TABLE_ENTRY_GPS; + + +#define _ls_ntp_ts( _x ) ( _x ## LL ) + + +/** + * @brief Initializer for a table of known leap seconds, with NTP times. + * + * Can be used to initialize a table of ::LS_TABLE_ENTRY entries. + * Values have been copied and can be updated from an NTP leap second file. + * + * The table can be incomplete after another leap second has been scheduled, + * unless this initializer is updated. + * + * The first value is the number of seconds since the NTP epoch, 1900-01-01, + * and the second value indicates how many seconds %UTC is ***behind TAI*** + * after the given date. + * + * There is also an initializer which uses a POSIX time_t for the date, and + * another one where the date is specified by a GPS week number plus day number. + * + * @see ::LS_TABLE_ENTRY + * @see ::KNOWN_LEAP_SECOND_INFO_POSIX + * @see ::KNOWN_LEAP_SECOND_INFO_GPS + */ +#define KNOWN_LEAP_SECOND_INFO_NTP \ +{ \ + { _ls_ntp_ts( 2272060800 ), 10 }, /* 1 Jan 1972 */ \ + { _ls_ntp_ts( 2287785600 ), 11 }, /* 1 Jul 1972 */ \ + { _ls_ntp_ts( 2303683200 ), 12 }, /* 1 Jan 1973 */ \ + { _ls_ntp_ts( 2335219200 ), 13 }, /* 1 Jan 1974 */ \ + { _ls_ntp_ts( 2366755200 ), 14 }, /* 1 Jan 1975 */ \ + { _ls_ntp_ts( 2398291200 ), 15 }, /* 1 Jan 1976 */ \ + { _ls_ntp_ts( 2429913600 ), 16 }, /* 1 Jan 1977 */ \ + { _ls_ntp_ts( 2461449600 ), 17 }, /* 1 Jan 1978 */ \ + { _ls_ntp_ts( 2492985600 ), 18 }, /* 1 Jan 1979 */ \ + { _ls_ntp_ts( 2524521600 ), 19 }, /* 1 Jan 1980 */ \ + { _ls_ntp_ts( 2571782400 ), 20 }, /* 1 Jul 1981 */ \ + { _ls_ntp_ts( 2603318400 ), 21 }, /* 1 Jul 1982 */ \ + { _ls_ntp_ts( 2634854400 ), 22 }, /* 1 Jul 1983 */ \ + { _ls_ntp_ts( 2698012800 ), 23 }, /* 1 Jul 1985 */ \ + { _ls_ntp_ts( 2776982400 ), 24 }, /* 1 Jan 1988 */ \ + { _ls_ntp_ts( 2840140800 ), 25 }, /* 1 Jan 1990 */ \ + { _ls_ntp_ts( 2871676800 ), 26 }, /* 1 Jan 1991 */ \ + { _ls_ntp_ts( 2918937600 ), 27 }, /* 1 Jul 1992 */ \ + { _ls_ntp_ts( 2950473600 ), 28 }, /* 1 Jul 1993 */ \ + { _ls_ntp_ts( 2982009600 ), 29 }, /* 1 Jul 1994 */ \ + { _ls_ntp_ts( 3029443200 ), 30 }, /* 1 Jan 1996 */ \ + { _ls_ntp_ts( 3076704000 ), 31 }, /* 1 Jul 1997 */ \ + { _ls_ntp_ts( 3124137600 ), 32 }, /* 1 Jan 1999 */ \ + { _ls_ntp_ts( 3345062400 ), 33 }, /* 1 Jan 2006 */ \ + { _ls_ntp_ts( 3439756800 ), 34 }, /* 1 Jan 2009 */ \ + { _ls_ntp_ts( 3550089600 ), 35 }, /* 1 Jul 2012 */ \ + { _ls_ntp_ts( 3644697600 ), 36 }, /* 1 Jul 2015 */ \ + { _ls_ntp_ts( 3692217600 ), 37 }, /* 1 Jan 2017 */ \ + /* =============================== */ \ + /* If a new entry is added, don't */ \ + /* forget to update the tables */ \ + /* KNOWN_LEAP_SECOND_INFO_POSIX */ \ + /* and KNOWN_LEAP_SECOND_INFO_GPS */ \ + /* accordingly. */ \ + /* =============================== */ \ + { 0, 0 } /* end-of-table */ \ +} + + + +#define _ls_ntp_to_posix( _x ) ( _ls_ntp_ts( _x ) - NTP_SEC_BIAS ) + +/** + * @brief Initializer for a table of known leap seconds, with POSIX times. + * + * Can be used to initialize a table of ::LS_TABLE_ENTRY entries. Numeric + * values have been copied and can be updated from an NTP leap second file, + * and an appropriate macro is used to convert the NTP times to POSIX. + * + * The table can be incomplete after another leap second has been scheduled, + * unless this initializer is updated. + * + * The resulting first value is the number of seconds since the POSIX epoch, + * 1970-01-01, and the second value indicates how many seconds %UTC is + * ***behind TAI*** after the given date. + * + * There is also an initializer which uses an NTP time for the date, and + * another one where the date is specified by a GPS week number + * plus day number. + * + * @see ::LS_TABLE_ENTRY + * @see ::KNOWN_LEAP_SECOND_INFO_NTP + * @see ::KNOWN_LEAP_SECOND_INFO_GPS + */ +#define KNOWN_LEAP_SECOND_INFO_POSIX \ +{ \ + { _ls_ntp_to_posix( 2272060800 ), 10 }, /* 1 Jan 1972 */ \ + { _ls_ntp_to_posix( 2287785600 ), 11 }, /* 1 Jul 1972 */ \ + { _ls_ntp_to_posix( 2303683200 ), 12 }, /* 1 Jan 1973 */ \ + { _ls_ntp_to_posix( 2335219200 ), 13 }, /* 1 Jan 1974 */ \ + { _ls_ntp_to_posix( 2366755200 ), 14 }, /* 1 Jan 1975 */ \ + { _ls_ntp_to_posix( 2398291200 ), 15 }, /* 1 Jan 1976 */ \ + { _ls_ntp_to_posix( 2429913600 ), 16 }, /* 1 Jan 1977 */ \ + { _ls_ntp_to_posix( 2461449600 ), 17 }, /* 1 Jan 1978 */ \ + { _ls_ntp_to_posix( 2492985600 ), 18 }, /* 1 Jan 1979 */ \ + { _ls_ntp_to_posix( 2524521600 ), 19 }, /* 1 Jan 1980 */ \ + { _ls_ntp_to_posix( 2571782400 ), 20 }, /* 1 Jul 1981 */ \ + { _ls_ntp_to_posix( 2603318400 ), 21 }, /* 1 Jul 1982 */ \ + { _ls_ntp_to_posix( 2634854400 ), 22 }, /* 1 Jul 1983 */ \ + { _ls_ntp_to_posix( 2698012800 ), 23 }, /* 1 Jul 1985 */ \ + { _ls_ntp_to_posix( 2776982400 ), 24 }, /* 1 Jan 1988 */ \ + { _ls_ntp_to_posix( 2840140800 ), 25 }, /* 1 Jan 1990 */ \ + { _ls_ntp_to_posix( 2871676800 ), 26 }, /* 1 Jan 1991 */ \ + { _ls_ntp_to_posix( 2918937600 ), 27 }, /* 1 Jul 1992 */ \ + { _ls_ntp_to_posix( 2950473600 ), 28 }, /* 1 Jul 1993 */ \ + { _ls_ntp_to_posix( 2982009600 ), 29 }, /* 1 Jul 1994 */ \ + { _ls_ntp_to_posix( 3029443200 ), 30 }, /* 1 Jan 1996 */ \ + { _ls_ntp_to_posix( 3076704000 ), 31 }, /* 1 Jul 1997 */ \ + { _ls_ntp_to_posix( 3124137600 ), 32 }, /* 1 Jan 1999 */ \ + { _ls_ntp_to_posix( 3345062400 ), 33 }, /* 1 Jan 2006 */ \ + { _ls_ntp_to_posix( 3439756800 ), 34 }, /* 1 Jan 2009 */ \ + { _ls_ntp_to_posix( 3550089600 ), 35 }, /* 1 Jul 2012 */ \ + { _ls_ntp_to_posix( 3644697600 ), 36 }, /* 1 Jul 2015 */ \ + { _ls_ntp_to_posix( 3692217600 ), 37 }, /* 1 Jan 2017 */ \ + /* =================================================== */ \ + /* If a new entry is added, don't forget to update */ \ + /* the tables KNOWN_LEAP_SECOND_INFO_NTP and */ \ + /* KNOWN_LEAP_SECOND_INFO_GPS accordingly. */ \ + /* =================================================== */ \ + { 0, 0 } /* end-of-table */ \ +} + + + +#define _ls_ntp_to_gps( _x ) \ + ( ( _ls_ntp_ts( _x ) - NTP_SEC_BIAS - GPS_SEC_BIAS ) / SECS_PER_WEEK ), \ + ( ( ( _ls_ntp_ts( _x ) - NTP_SEC_BIAS - GPS_SEC_BIAS ) % SECS_PER_WEEK ) / SECS_PER_DAY ) + +#define _ls_utc_offs_to_gps( _x ) ( (_x) - GPS_TAI_OFFSET ) + +/** + * @brief Initializer for a table of known leap seconds, with GPS times. + * + * Can be used to initialize a table of ::LS_TABLE_ENTRY_GPS entries. Numeric + * values have been copied and can be updated from an NTP leap second file, + * and appropriate macros are used to convert the NTP times to GPS time. + * + * The table can be incomplete after another leap second has been scheduled, + * unless this initializer is updated. + * + * The resulting first value is an extended GPS week number, the second value + * is a day-of-week number, and the third value indicates how many seconds %UTC + * is ***behind GPS*** after the given date. + * + * ***Please note*** the resulting table does not include leap seconds before + * the GPS epoch, and it contains normalized wn|dn pairs like 1930|0, while + * the ::UTC info sent by the satellites could be 1929|7. So the dates from + * a GPS receiver should be normalized before being compared. + * + * There is also an initializer which uses an NTP time for the date, and + * another one where the date is specified by a POSIX time_t value. + * + * @see ::LS_TABLE_ENTRY + * @see ::KNOWN_LEAP_SECOND_INFO_NTP + * @see ::KNOWN_LEAP_SECOND_INFO_POSIX + */ +#define KNOWN_LEAP_SECOND_INFO_GPS \ +{ \ + { _ls_ntp_to_gps( 2571782400 ), _ls_utc_offs_to_gps( 20 ) }, /* 1 Jul 1981 */ \ + { _ls_ntp_to_gps( 2603318400 ), _ls_utc_offs_to_gps( 21 ) }, /* 1 Jul 1982 */ \ + { _ls_ntp_to_gps( 2634854400 ), _ls_utc_offs_to_gps( 22 ) }, /* 1 Jul 1983 */ \ + { _ls_ntp_to_gps( 2698012800 ), _ls_utc_offs_to_gps( 23 ) }, /* 1 Jul 1985 */ \ + { _ls_ntp_to_gps( 2776982400 ), _ls_utc_offs_to_gps( 24 ) }, /* 1 Jan 1988 */ \ + { _ls_ntp_to_gps( 2840140800 ), _ls_utc_offs_to_gps( 25 ) }, /* 1 Jan 1990 */ \ + { _ls_ntp_to_gps( 2871676800 ), _ls_utc_offs_to_gps( 26 ) }, /* 1 Jan 1991 */ \ + { _ls_ntp_to_gps( 2918937600 ), _ls_utc_offs_to_gps( 27 ) }, /* 1 Jul 1992 */ \ + { _ls_ntp_to_gps( 2950473600 ), _ls_utc_offs_to_gps( 28 ) }, /* 1 Jul 1993 */ \ + { _ls_ntp_to_gps( 2982009600 ), _ls_utc_offs_to_gps( 29 ) }, /* 1 Jul 1994 */ \ + { _ls_ntp_to_gps( 3029443200 ), _ls_utc_offs_to_gps( 30 ) }, /* 1 Jan 1996 */ \ + { _ls_ntp_to_gps( 3076704000 ), _ls_utc_offs_to_gps( 31 ) }, /* 1 Jul 1997 */ \ + { _ls_ntp_to_gps( 3124137600 ), _ls_utc_offs_to_gps( 32 ) }, /* 1 Jan 1999 */ \ + { _ls_ntp_to_gps( 3345062400 ), _ls_utc_offs_to_gps( 33 ) }, /* 1 Jan 2006 */ \ + { _ls_ntp_to_gps( 3439756800 ), _ls_utc_offs_to_gps( 34 ) }, /* 1 Jan 2009 */ \ + { _ls_ntp_to_gps( 3550089600 ), _ls_utc_offs_to_gps( 35 ) }, /* 1 Jul 2012 */ \ + { _ls_ntp_to_gps( 3644697600 ), _ls_utc_offs_to_gps( 36 ) }, /* 1 Jul 2015 */ \ + { _ls_ntp_to_gps( 3692217600 ), _ls_utc_offs_to_gps( 37 ) }, /* 1 Jan 2017 */ \ + /* ======================================================================== */ \ + /* If a new entry is added, don't forget to update the tables */ \ + /* KNOWN_LEAP_SECOND_INFO_NTP and KNOWN_LEAP_SECOND_INFO_POSIX */ \ + /* accordingly. */ \ + /* ======================================================================== */ \ + { 0, 0, 0 } /* end-of-tbl */ \ +} + + + +/** + * @brief Number of 256-week-cycles to check for true leap second week number. + * + * The number of 256-week-cycles to check in ::find_true_gps_wn_lsf or + * ::mbg_find_true_gps_wn_lsf when trying to resolve the ambiguity of + * the 8 bit truncated week number in ::UTC::WNlsf. + * + * According to some tests, the results are not ambiguous for 25 + * 256-week cycles after 1980 (i.e. until year 2099), if only + * leap second dates at the end of June / beginning of July or + * end of December / beginning of January are taken into account. + * + * @see ::mbg_find_true_gps_wn_lsf (Meinberg API) + * @see ::find_true_gps_wn_lsf (Meinberg firmware) + * @see ::ACCEPT_LS_APR_OCT + */ +#define N_GPS_WN_EPOCH 25 + + +#if !defined( ACCEPT_LS_APR_OCT ) + #define ACCEPT_LS_APR_OCT 0 + ///< Should be 0, otherwise ::find_true_gps_wn_lsf or + ///< ::mbg_find_true_gps_wn_lsf may fail. + ///< See also ::N_GPS_WN_EPOCH +#endif + + + +/** + * @brief Convert a 16 bit binary fraction to a scaled decimal + * + * @param[in] bin The binary fraction + * @param[in] scale The scale factor + * + * @return The calculated number + * + * @see ::dec_frac_to_bin_frac_16 + * @see ::dec_frac_to_bin_frac_32 + * @see ::bin_frac_32_to_dec_frac + */ +static __mbg_inline /*HDR*/ +uint32_t bin_frac_16_to_dec_frac( uint16_t bin, uint32_t scale ) +{ + return (uint32_t) ( (MBG_FRAC32_CONVERSION_TYPE) bin * scale + / 0x10000UL ); + +} // bin_frac_16_to_dec_frac + + + +/** + * @brief Convert a 32 bit binary fraction to a scaled decimal + * + * @param[in] bin The binary fraction + * @param[in] scale The scale factor + * + * @return The calculated number + * + * @see ::dec_frac_to_bin_frac_32 + * @see ::dec_frac_to_bin_frac_16 + * @see ::bin_frac_16_to_dec_frac + */ +static __mbg_inline /*HDR*/ +uint32_t bin_frac_32_to_dec_frac( uint32_t bin, uint32_t scale ) +{ + return (uint32_t) ( (MBG_FRAC32_CONVERSION_TYPE) bin * scale + / MBG_FRAC32_UNITS_PER_SEC ); + +} // bin_frac_32_to_dec_frac + + + +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + +// On targets which don't provide 64 bit data types +// MBG_FRAC32_CONVERSION_TYPE is defined as double, +// in which case the ">> 1" operation in the 2 functions +// below yields an "invalid use of floating point" error. +// This could probably be fixed by a different way of +// casting, at least for a partial expression. + +static __mbg_inline /*HDR*/ +uint16_t dec_frac_to_bin_frac_16( MBG_FRAC32_CONVERSION_TYPE dec, uint32_t scale ) +{ + return (uint16_t) ( ( ( dec * 0x20000 / scale ) + 1 ) >> 1 ); + +} // dec_frac_to_bin_frac_16 + + +static __mbg_inline /*HDR*/ +uint32_t dec_frac_to_bin_frac_32( MBG_FRAC32_CONVERSION_TYPE dec, uint32_t scale ) +{ + return (uint32_t) ( ( ( dec * MBG_FRAC32_UNITS_PER_SEC * 2 / scale ) + 1 ) >> 1 ); + +} // dec_frac_to_bin_frac_32 + +#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + + + +#define bin_frac_32_to_msec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000L ) +#define bin_frac_32_to_usec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000000L ) +#define bin_frac_32_to_nsec( _bin ) bin_frac_32_to_dec_frac( (_bin), 1000000000L ) +#define bin_frac_16_to_msec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000L ) +#define bin_frac_16_to_usec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000000L ) +#define bin_frac_16_to_nsec( _bin ) bin_frac_16_to_dec_frac( (_bin), 1000000000L ) + + +#define msec_to_bin_frac_32( _msec ) dec_frac_to_bin_frac_32( (_msec), 1000L ) +#define usec_to_bin_frac_32( _usec ) dec_frac_to_bin_frac_32( (_usec), 1000000L ) +#define nsec_to_bin_frac_32( _nsec ) dec_frac_to_bin_frac_32( (_nsec), 1000000000L ) +#define msec_to_bin_frac_16( _msec ) dec_frac_to_bin_frac_16( (_msec), 1000L ) +#define usec_to_bin_frac_16( _usec ) dec_frac_to_bin_frac_16( (_usec), 1000000L ) +#define nsec_to_bin_frac_16( _nsec ) dec_frac_to_bin_frac_16( (_nsec), 1000000000L ) + + + +/** + * @brief Convert a binary fraction to a scaled decimal + * + * Convert a binary fraction (e.g. as in ::PCPS_TIME_STAMP::frac) + * to a decimal fraction, using a specified scale factor. Depending + * on the @p scale factor, the result can be milliseconds, microseconds, + * nanoseconds, or whatever. + * + * This function is actually just an alias for ::bin_frac_32_to_dec_frac, + * but has been introduced much erlier than the latter, and thus is kept + * for compatibility reasons. + * + * @param[in] b The binary fraction + * @param[in] scale The scale factor + * + * @return The calculated number + * + * @see ::bin_frac_32_to_dec_frac + */ +static __mbg_inline /*HDR*/ +uint32_t frac_sec_from_bin( uint32_t b, uint32_t scale ) +{ + return bin_frac_32_to_dec_frac( b, scale ); + +} // frac_sec_from_bin + + + +/** + * @brief Convert a binary fraction to "double" fractions + * + * Convert a binary fraction (e.g. of a second, as in ::PCPS_TIME_STAMP::frac) + * to a "double" with the units of seconds.<br> + * E.g. a 0xFFFFFFFF fraction yields 0.9999999999.... + * + * @note Excluded from build for kernel drivers which usually + * don't support floating point operations. + * + * @param[in] b The binary fraction + * + * @return The calculated fraction + * + * @see ::MBG_FRAC32_UNITS_PER_SEC + */ +static __mbg_inline /*HDR*/ +double dfrac_sec_from_bin( uint32_t b ) +{ + return (double) b / (double) MBG_FRAC32_UNITS_PER_SEC; + +} // dfrac_sec_from_bin + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if a particular date is a valid leap second date. + * + * This generic function expects a day of month, and a month. + * + * @param[in] mday The day of month of the date to be checked, range [1..31]. + * @param[in] month The month of the date to be checked, range [1..12]. + * + * @return @a true if considered valid, else @a false. + * + * @ingroup leap_date_valid_fncs + * @see @ref leap_date_valid_fncs + * @see ::is_valid_leap_second_date_tm_gps + * @see ::is_valid_leap_second_date_tm + */ +bool is_valid_leap_second_date( int mday, int month ) +{ + if ( mday != 1 ) + return false; + + if ( ( month == 1 ) || ( month == 7 ) ) // 1st of January or July + return true; + + #if ACCEPT_LS_APR_OCT + if ( ( month == 4 ) || ( month == 10 ) ) // 1st of April or October + return true; + #endif + + return false; + +} // is_valid_leap_second_date + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if a particular date in ::TM_GPS format is a valid leap second date. + * + * For detailed hints see @ref leap_date_valid_fncs and @ref leap_date_valid_fncs. + * + * This function expects a ::TM_GPS parameter and calls + * a generic function to actually check the date. + * + * @param[in] p_tm_gps The date to be checked, in ::TM_GPS format. + * + * @return @a true if considered valid, else @a false. + * + * @ingroup leap_date_valid_fncs + * @see @ref leap_date_valid_fncs + * @see ::is_valid_leap_second_date_tm + * @see ::is_valid_leap_second_date + */ +bool is_valid_leap_second_date_tm_gps( const TM_GPS *p_tm_gps ) +{ + return is_valid_leap_second_date( p_tm_gps->mday, p_tm_gps->month ); + +} // is_valid_leap_second_date_tm_gps + + + +static __mbg_inline /*HDR*/ +/** + * @brief Check if a particular date in <em>struct tm</em> format is a valid leap second date. + * + * We expect the date and time immediately ***after*** a leap second, + * i.e. when a new TAI offset becomes valid. For example, we expect + * 2017-01-01 00:00:00 instead of 2016-12-31 23:59:59. + * This should work for both inserted and deleted leap seconds. + * + * By default, only dates at the beginning of January or or July are + * considered valid. + * + * This function expects a <em>struct tm</em> parameter and calls + * a generic function to actually check the date. + * + * @param[in] p_tm The date to be checked, in <em>struct tm</em> format. + * + * @return @a true if considered valid, else @a false. + * + * @ingroup leap_date_valid_fncs + * @see @ref leap_date_valid_fncs + * @see ::is_valid_leap_second_date_tm_gps + * @see ::is_valid_leap_second_date + */ +bool is_valid_leap_second_date_tm( const struct tm *p_tm ) +{ + return is_valid_leap_second_date( p_tm->tm_mday, p_tm->tm_mon + 1 ); + +} // is_valid_leap_second_date_tm + + +#endif // !defined( MBG_TGT_KERNEL ) + + + /* ----- function prototypes begin ----- */ /* This section was generated automatically */ /* by MAKEHDR, do not remove the comments. */ + /** + * @brief Set a timeout object to specified interval + * + * @param[out] t The timeout object + * @param[in] clk The current time, in clock_t ticks + * @param[in] interval The interval until expiration, in clock_t ticks + */ void set_timeout( TIMEOUT *t, clock_t clk, clock_t interval ) ; + + /** + * @brief Stretch a timeout specified in given timeout object + * + * @param[in,out] t The timeout object + * @param[in] interval The interval until expiration, in clock_t ticks + */ void stretch_timeout( TIMEOUT *t, clock_t interval ) ; + + /** + * @brief Check if a timeout object has expired + * + * @param[in] t The timeout object + * @param[in] clk The current time, in clock_t ticks + * + * @return 1 if timeout expired, else 0 + */ bit check_timeout( TIMEOUT *t, clock_t clk ) ; - int err_tm( TM_GPS *tm ) ; + + /** + * @brief Check if a ::TM_GPS structure contains a valid date and time + * + * @param[in] tm The date/time structure to be checked + * + * @return 0 if date/time is valid, else a negative number indicating + * which field was found invalid + */ + int err_tm( const TM_GPS *tm ) ; + + /** + * @brief Set the time in a ::TM_GPS structure to 00:00:00.000 + * + * @param[in,out] tm The date/time structure to be set + * + * @return Pointer to the ::TM_GPS structure that has been passed + */ TM_GPS *clear_time( TM_GPS *tm ) ; + + /** + * @brief Convert second-of-week to day-of-week and time-of-day + * + * @param[in] wsec The second-of-week number to be converted. + * Must not be negative. + * @param[out] tm Address of a ::TM_GPS structure which takes + * the computed results. Updates the fields + * ::TM_GPS::hour, ::TM_GPS::min, ::TM_GPS::sec, + * and ::TM_GPS::wday in the range 0..6, with + * 0 = Sunday. + * + * @return Pointer to the ::TM_GPS structure that has been passed + * + * @see ::tm_to_wsec + * @see ::day_of_week_sun06 + */ TM_GPS *wsec_to_tm( long wsec, TM_GPS *tm ) ; - long tm_to_wsec( TM_GPS *tm ) ; + + /** + * @brief Compute second-of-week from day-of-week and time-of-day + * + * @todo Specify input / output ranges + * + * @param[in] tm Address of a ::TM_GPS structure providing day-of-week and time-of-day + * + * @return The computed second-of-week number + * + * @see ::wsec_to_tm + */ + long tm_to_wsec( const TM_GPS *tm ) ; + + /** + * @brief Check if a specific year is a leap year + * + * @param[in] y The full year number + * + * @return != 0 if the year is a leap year, else 0 + */ int is_leap_year( int y ) ; + + /** + * @brief Compute the day-of-year from a given date + * + * @param[in] day The day-of-month + * @param[in] month The month + * @param[in] year The full year number + * + * @return The computed day-of-year + */ int day_of_year( int day, int month, int year ) ; - void date_of_year ( int year, int day_num, TM_GPS *tm ) ; + + /** + * @brief Compute a date from a given year and day-of-year + * + * @param[in] year The full year number + * @param[in] day_num Number of days from the beginning of that year, may be negative + * @param[out] tm Address of a ::TM_GPS structure which takes the computed results + */ + void date_of_year( int year, int day_num, TM_GPS *tm ) ; + + /** + * @brief Compute day-of-week for a given date. + * + * ATTENTION: The computed day-of-week is in the range 0..6, + * with 0 = Monday (!). + * + * In most cases the function ::day_of_week_sun06 is + * more suitable for applications. + * + * @param[in] day The day-of-month, 0..31 + * @param[in] month The month, 1..12 + * @param[in] year The full year number + * + * @return The computed day-of-week, 0..6, 0 = Monday (!) + * + * @see ::day_of_week_sun06 + * @see ::n_days + */ int day_of_week( int day, int month, int year ) ; + + /** + * @brief Compute day-of-week for a given date. + * + * The computed day-of-week is in the range 0..6, + * with 0 = Sunday, as expected by most applications. + * + * @param[in] day The day-of-month, 0..31 + * @param[in] month The month, 1..12 + * @param[in] year The full year number + * + * @return The computed day-of-week, 0..6, with 0 = Sunday. + * + * @see ::n_days + * @see ::wsec_to_tm + */ + int day_of_week_sun06( int day, int month, int year ) ; + + /** + * @brief Update a year number by a number of days, accounting for leap years + * + * @param[in] day_num The number of days to evaluate + * @param[in] year The year number to start with + * + * @return The computed year number + */ int days_to_years( long *day_num, int year ) ; - long n_days( ushort mday, ushort month, ushort year ) ; - double nano_time_to_double( const NANO_TIME *p ) ; - void double_to_nano_time( NANO_TIME *p, double d ) ; + + /** + * @brief Compute number of days after Jan 1, 0000 for a given date + * + * @param[in] mday The day-of-month + * @param[in] month The month + * @param[in] year The full year number + * + * @return The computed number of days + * + * @see ::day_of_week + */ + long n_days( int mday, int month, int year ) ; + + /** + * @brief Search a table of known past leap second dates for a specific week and day number. + * + * Optionally we return the latest week number we + * have found in the table, so an application can + * start there searching there for future potential + * leap second dates. + * + * @ingroup group_true_gps_wn_fncs + */ + int find_past_gps_wn_lsf_from_table( GPS_WNUM *p_wn, GPS_DNUM dn_t, int srch_all, GPS_WNUM *p_wn_last ) ; + + /** + * @brief Print time with hours, minutes, seconds to a string + * + * @param[out] s Address of a string buffer to be filled + * @param[in] tm Address of a ::TM_GPS structure providing date and time + */ int sprint_time( char *s, const TM_GPS *tm ) ; - int sprint_short_time( char *s, TM_GPS *time ) ; + + /** + * @brief Print time with hours, minutes to a string + * + * @param[out] s Address of a string buffer to be filled + * @param[in] tm Address of a ::TM_GPS structure providing date and time + */ + int sprint_short_time( char *s, const TM_GPS *tm ) ; + + /** + * @brief Print date to a string + * + * @param[out] s Address of a string buffer to be filled + * @param[in] tm Address of a ::TM_GPS structure providing date and time + */ int sprint_date( char *s, const TM_GPS *tm ) ; + + /** + * @brief Print day-of-week and date to a string + * + * @param[out] s Address of a string buffer to be filled + * @param[in] tm Address of a ::TM_GPS structure providing date and time + */ int sprint_day_date( char *s, const TM_GPS *tm ) ; + + /** + * @brief Print day-of-week, date and time to a string + * + * @param[out] s Address of a string buffer to be filled + * @param[in] tm Address of a ::TM_GPS structure providing date and time + */ int sprint_tm( char *s, const TM_GPS *tm ) ; - void sscan_time( char *s, TM_GPS *tm ) ; + + /** + * @brief Extract a time from a string + * + * @param[in] s A time string in format hh:mm:ss + * @param[out] tm Address of a ::TM_GPS structure which takes the extracted time + */ + void sscan_time( const char *s, TM_GPS *tm ) ; + + /** + * @brief Extract a date from a string + * + * @param[in] s A date string in format dd.mm. or dd.mm.yyyy + * @param[out] tm Address of a ::TM_GPS structure which takes the extracted date + */ void sscan_date( char *s, TM_GPS *tm ) ; + /* ----- function prototypes end ----- */ @@ -362,6 +1491,7 @@ _ext DAYS_OF_MONTH_TABLE days_of_month #undef _ext +#undef _DO_INIT #ifdef __cplusplus } diff --git a/c/mbglib/include/mbgutil.h b/c/mbglib/include/mbgutil.h index a12c713..b16b80f 100644 --- a/c/mbglib/include/mbgutil.h +++ b/c/mbglib/include/mbgutil.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: mbgutil.h 1.17.1.8 2014/05/27 11:32:47Z martin TRASH martin $ + * $Id: mbgutil.h 1.22.1.1 2019/08/19 11:13:08Z martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,15 +10,21 @@ * * ----------------------------------------------------------------------- * $Log: mbgutil.h $ - * Revision 1.17.1.8 2014/05/27 11:32:47Z martin - * Revision 1.17.1.7 2014/03/13 16:04:12 martin - * Revision 1.17.1.6 2014/03/13 15:45:37 martin - * Revision 1.17.1.5 2014/03/13 14:58:52Z martin - * Revision 1.17.1.4 2014/03/13 14:31:53Z martin - * Revision 1.17.1.3 2014/03/05 10:38:30Z martin - * Windows.h is now included in mbg_tgt.h. - * Revision 1.17.1.2 2013/10/23 10:40:53Z martin - * Revision 1.17.1.1 2013/10/22 10:06:01 martin + * Revision 1.22.1.1 2019/08/19 11:13:08Z martin + * Preliminary doxygen changes. + * Revision 1.22 2019/07/31 15:55:50 martin + * Updated function prototypes. + * Revision 1.21 2018/09/21 08:18:05 martin + * New version code 0x0308, compatibility version still 0x0110. + * Revision 1.20 2018/08/13 14:54:24Z martin + * Updated function prototypes. + * Revision 1.19 2018/08/07 15:09:11Z martin + * New version code 0x0370, compatibility version still 0x0110. + * Revision 1.18 2017/07/05 16:44:35 martin + * New version code 0x0400, compatibility version still 0x0110. + * Include timeutil.h. + * windows.h is now included in mbg_tgt.h. + * Updated function prototypes. * Revision 1.17 2012/10/15 10:08:32 martin * Include stdlib.h. * Cleaned up handling of pragma pack(). @@ -64,6 +70,7 @@ /* Other headers to be included */ #include <mbg_tgt.h> +#include <timeutil.h> #include <use_pack.h> #include <pcpsdefs.h> #include <mbggeo.h> @@ -72,7 +79,7 @@ #include <stdlib.h> -#define MBGUTIL_VERSION 0x0306 +#define MBGUTIL_VERSION 0x0308 #define MBGUTIL_COMPAT_VERSION 0x0110 @@ -111,24 +118,11 @@ #endif -#if defined( MBG_TGT_WIN32 ) - -#elif defined( MBG_TGT_LINUX ) - -#elif defined( MBG_TGT_OS2 ) - -#else - -#endif - - - -/* function prototypes: */ - #ifdef __cplusplus extern "C" { #endif + // The macro below can be used to simplify the API call if // a string variable is used rather than a char *. #define _mbg_strncpy( _s, _src ) \ @@ -141,83 +135,467 @@ extern "C" { /* by MAKEHDR, do not remove the comments. */ /** - * @brief Get the DLL/shared library's version code + * @brief Get the version number of the precompiled DLL/shared object library. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API function are called + * in the correct way. * - * @return The version code at which the library was built + * @return The version number. + * + * @see ::mbgutil_check_version + * @see ::MBGUTIL_VERSION defined in mbgutil.h */ _MBG_API_ATTR int _MBG_API mbgutil_get_version( void ) ; /** - * @brief Check the DLL/shared library's compatibility + * @brief Check if the DLL/shared library is compatible with a given version. + * + * If this library is used as a DLL/shared object library then the version + * number can be checked to see if the header files which are actually used + * to build an application are compatible with the header files which have + * been used to build the library, and thus the API functions are called + * in the correct way. + * + * @param[in] header_version Version number to be checked, should be ::MBGUTIL_VERSION + * from the mbgutil.h file version used to build the application * - * @param header_version Version code defined in the header file when the application is built + * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE. * - * @return ::MBG_SUCCESS if compatible, else ::MBG_ERR_LIB_NOT_COMPATIBLE + * @see ::mbgutil_get_version + * @see ::MBGUTIL_VERSION defined in mbgutil.h */ _MBG_API_ATTR int _MBG_API mbgutil_check_version( int header_version ) ; /** - * @brief A portable implementation of snprintf() + * @brief A portable, safer implementation of snprintf(). * - * Under Windows _snprintf() returns -1 and does not write - * a terminating 0 if the output exceeds the buffer size. - * - * This function terminates the output string properly. However, - * the maximum return value is (max_len - 1), so the function - * can not be used to determine the buffer size that would be - * required for an untruncated string. + * The output string buffer is in any case properly terminated by 0. + * For a detailed description see ::vsnprintf_safe. * - * @param s pointer to the output buffer - * @param max_len size of the output buffer - * @param fmt format string according to subsequent parameters - * @param ... variable argument list according to the format string + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] fmt Format string according to subsequent parameters + * @param[in] ... Variable argument list according to the format string * - * @return the number of characters written to the output buffer, except the terminating 0 + * @return The number of characters written to the output buffer, except the terminating 0 + * + * @see ::vsnprintf_safe + * @see ::snprintf_safe */ - _MBG_API_ATTR int __attribute__( ( format( printf, 3, 4 ) ) ) _MBG_API mbg_snprintf( char *s, size_t max_len, const char * fmt, ... ) ; + __attribute__( ( format( printf, 3, 4 ) ) ) _MBG_API_ATTR int _MBG_API mbg_snprintf( char *s, size_t max_len, const char * fmt, ... ) ; + /** + * @brief A portable, safe implementation of strncpy() + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the destination string buffer + * @param[in] max_len Size of the destination string buffer + * @param[in] src Pointer to the source string buffer + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_strncpy( char *s, size_t max_len, const char *src ) ; + /** * @brief Write a character multiple times to a string buffer * - * Append a terminating 0 to the buffer. + * The output string buffer is in any case properly terminated by 0. * - * @param s pointer to the output buffer - * @param max_len size of the output buffer - * @param c the character to write to the output buffer - * @param n the number of characters to write to the output buffer + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] c The character to write to the output buffer + * @param[in] n The number of characters to write to the output buffer * * @return the number of characters written to the output buffer, except the terminating 0 */ _MBG_API_ATTR int _MBG_API mbg_strchar( char *s, size_t max_len, char c, size_t n ) ; - _MBG_API_ATTR int _MBG_API mbg_str_date_short( char *s, int max_len, int mday, int month ) ; - _MBG_API_ATTR int _MBG_API mbg_str_date( char *s, int max_len, int mday, int month, int year ) ; - _MBG_API_ATTR int _MBG_API mbg_str_time_short( char *s, int max_len, int hour, int min ) ; + /** + * @brief Write a short date string "dd.mm." to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] mday Day-of-month number, 1..31 + * @param[in] month Month number, 1..12 + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_date_short( char *s, int max_len, int mday, int month ) ; + + /** + * @brief Write a date string "dd.mm.yyyy" to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] mday Day-of-month number, 1..31 + * @param[in] month Month number, 1..12 + * @param[in] year Year number + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_date( char *s, int max_len, int mday, int month, int year ) ; + + /** + * @brief Write a short time string "hh:mm" to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] hour Hours number, 0..23 + * @param[in] min Minutes number, 0..59 + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_time_short( char *s, int max_len, int hour, int min ) ; + + /** + * @brief Write a time string "hh:mm:ss" to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] hour Hours number, 0..23 + * @param[in] min Minutes number, 0..59 + * @param[in] sec Seconds number, 0..59, or 60 in case of leap second + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_time( char *s, int max_len, int hour, int min, int sec ) ; + + /** + * @brief Write a long time string "hh:mm:ss.cc" to a string buffer + * + * Include 100ths of seconds. + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] hour Hours number, 0..23 + * @param[in] min Minutes number, 0..59 + * @param[in] sec Seconds number, 0..59, or 60 in case of leap second + * @param[in] sec100 Hundreths of seconds, 0..99 + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_time_long( char *s, int max_len, int hour, int min, int sec, int sec100 ) ; + + /** + * @brief Write a full date and time string to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::TM_GPS structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_tm_gps_date_time( char *s, int max_len, const TM_GPS *pt ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_short( char *s, int max_len, const PCPS_TIME *pt ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_date( char *s, int max_len, const PCPS_TIME *pt ) ; + + /** + * @brief Write the short date given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_short( char *s, int max_len, const PCPS_TIME *pt ) ; + + /** + * @brief Write the date given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_date( char *s, int max_len, const PCPS_TIME *pt ) ; + + /** + * @brief Write the short time given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time_short( char *s, int max_len, const PCPS_TIME *pt ) ; + + /** + * @brief Write the time given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time( char *s, int max_len, const PCPS_TIME *pt ) ; + + /** + * @brief Write the time including sec100ths given as ::PCPS_TIME structure to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_time_long( char *s, int max_len, const PCPS_TIME *pt ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_time( char *s, int max_len, const PCPS_TIME *pt, const char *tz_str ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date( char *s, int max_len, uint32_t sec ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time( char *s, int max_len, uint32_t sec ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write date and time given as ::PCPS_TIME structure to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_TIME structure providing date and time + * @param[in] tz_str Optional time zone string to be appended, currently not used, may be NULL + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_date_time( char *s, int max_len, const PCPS_TIME *pt, const char *tz_str ) ; + + /** + * @brief Write date derived from seconds-since-epoch to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] sec Number of seconds since the epoch to be converted to date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date( char *s, int max_len, uint32_t sec ) ; + + /** + * @brief Write time derived from seconds-since-epoch to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] sec Number of seconds since the epoch to be converted to date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time( char *s, int max_len, uint32_t sec ) ; + + /** + * @brief Write UTC date and time given as ::PCPS_HR_TIME structure to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write local date and time given as ::PCPS_HR_TIME structure to a string buffer + * + * The number of space characters between date and time + * is determined by the global variable ::mbg_date_time_dist. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_date_time_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Print binary ::PCPS_FRAC_32 fractions in decimal to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] frac Binary fractions of a second in ::PCPS_FRAC_32 format + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_frac( char *s, int max_len, uint32_t frac ) ; + + /** + * @brief Print the UTC offset from a ::PCPS_HR_TIME structure to a string buffer + * + * The output format is sign - hours - minutes, e.g. "+01:45h". + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date, and UTC offset + * @param[in] info An informational text to be prepended + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_offs( char *s, int max_len, const PCPS_HR_TIME *pt, const char *info ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_tstamp_raw( char *s, int max_len, const PCPS_TIME_STAMP *pt ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_raw( char *s, int max_len, const PCPS_HR_TIME *pt ) ; - _MBG_API_ATTR int _MBG_API mbg_str_ucap( char *s, int max_len, const PCPS_HR_TIME *pt ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pos_dms( char *s, int max_len, const DMS *pdms, int prec ) ; + + /** + * @brief Write a high resolution UTC time stamp including fractions to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_utc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write a high resolution local time stamp including fractions to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_tstamp_loc( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write a raw high resolution time stamp to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_tstamp_raw( char *s, int max_len, const PCPS_TIME_STAMP *pt ) ; + + /** + * @brief Write a raw high resolution time stamp plus converted local time to a string buffer + * + * The output string also has the time status code appended as hex number. + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure providing date and time + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pcps_hr_time_raw( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write time capture / user capture time stamp to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pt Pointer to a ::PCPS_HR_TIME structure containing a user capture event + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_ucap( char *s, int max_len, const PCPS_HR_TIME *pt ) ; + + /** + * @brief Write a geographic coordinate in degrees - minutes - seconds to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] pdms Pointer to a ::DMS structure containing the coordinate + * @param[in] prec Number of digits of the geographic seconds after the decimal separator + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pos_dms( char *s, int max_len, const DMS *pdms, int prec ) ; + + /** + * @brief Write a position's altitude parameter to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] alt The altitude parameter, in meters + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ _MBG_API_ATTR int _MBG_API mbg_str_pos_alt( char *s, int max_len, double alt ) ; - _MBG_API_ATTR int _MBG_API mbg_str_pos( char *s, int max_len, const POS *ppos, int prec ) ; - _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *short_name, uint16_t fw_rev_num, PCI_ASIC_VERSION asic_version_num ) ; + + /** + * @brief Write geographic coordinates to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] ppos Pointer to a ::POS structure containing the coordinates + * @param[in] prec Number of digits of the geographic seconds after the decimal separator + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_pos( char *s, int max_len, const POS *ppos, int prec ) ; + + /** + * @brief Write device info to a string buffer + * + * The output string buffer is in any case properly terminated by 0. + * + * @param[out] s Pointer to the output buffer + * @param[in] max_len Size of the output buffer + * @param[in] short_name Short device name, e.g. in ::MBG_DEV_NAME format + * @param[in] fw_rev_num The firmware revision number + * @param[in] asic_ver_num The ASIC version number + * + * @return the number of characters written to the output buffer, except the terminating 0 + */ + _MBG_API_ATTR int _MBG_API mbg_str_dev_name( char *s, int max_len, const char *short_name, uint16_t fw_rev_num, PCI_ASIC_VERSION asic_ver_num ) ; + /* ----- function prototypes end ----- */ diff --git a/c/mbglib/include/messages.h b/c/mbglib/include/messages.h deleted file mode 100644 index 2a3e99e..0000000 --- a/c/mbglib/include/messages.h +++ /dev/null @@ -1,1151 +0,0 @@ - -/************************************************************************** - * - * $Id: messages.h 1.10 2009/12/15 15:35:59Z daniel REL_M $ - * $Name: $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * This file contains the message definitions for the Win32 - * syslog support messages for the mbgsvctl DLL. - * - * ----------------------------------------------------------------------- - * $Log: messages.h $ - * Revision 1.10 2009/12/15 15:35:59Z daniel - * Support new message codes for GPS mode and antenna status. - * Revision 1.10 2009/03/11 10:09:34Z daniel - * New codes regarding different time scales - * Revision 1.9 2009/01/14 11:31:35Z daniel - * Added new codes. - * Revision 1.8.1.3 2009/01/05 09:08:08Z daniel - * Revision 1.8.1.2 2008/11/21 11:08:45Z daniel - * Revision 1.8.1.1 2008/04/17 14:27:00Z daniel - * Revision 1.7 2008/02/06 10:01:14Z daniel - * 3 new commands - * Revision 1.6 2008/02/05 14:57:48Z daniel - * Added new code. - * Revision 1.5 2008/01/18 14:43:29Z daniel - * Adjusted code. - * Revision 1.4 2008/01/09 16:24:15Z daniel - * New message codes regarding batch file execution on status change. - * Revision 1.3 2007/09/26 15:00:11Z martin - * Added new language specific message codes and strings. - * Revision 1.2 2003/10/28 15:18:02Z martin - * Changed default language to unspecified. - * Added file header. - * Revision 1.1 2002/10/14 10:00:38Z Udo - * Initial revision - * - **************************************************************************/ - - /* - Microsoft Developer Support - Copyright 1992 - 1999 Microsoft Corporation - - This file contains the message definitions for the Win32 - messages.exe sample program. -------------------------------------------------------------------------- - HEADER SECTION - - The header section defines names and language identifiers for use - by the message definitions later in this file. The MessageIdTypedef, - SeverityNames, FacilityNames, and LanguageNames keywords are - optional and not required. - - - - The MessageIdTypedef keyword gives a typedef name that is used in a - type cast for each message code in the generated include file. Each - message code appears in the include file with the format: #define - name ((type) 0xnnnnnnnn) The default value for type is empty, and no - type cast is generated. It is the programmer's responsibility to - specify a typedef statement in the application source code to define - the type. The type used in the typedef must be large enough to - accomodate the entire 32-bit message code. - - - - The SeverityNames keyword defines the set of names that are allowed - as the value of the Severity keyword in the message definition. The - set is delimited by left and right parentheses. Associated with each - severity name is a number that, when shifted left by 30, gives the - bit pattern to logical-OR with the Facility value and MessageId - value to form the full 32-bit message code. The default value of - this keyword is: - - SeverityNames=( - Success=0x0 - Informational=0x1 - Warning=0x2 - Error=0x3 - ) - - Severity values occupy the high two bits of a 32-bit message code. - Any severity value that does not fit in two bits is an error. The - severity codes can be given symbolic names by following each value - with :name - - - - The FacilityNames keyword defines the set of names that are allowed - as the value of the Facility keyword in the message definition. The - set is delimited by left and right parentheses. Associated with each - facility name is a number that, when shift it left by 16 bits, gives - the bit pattern to logical-OR with the Severity value and MessageId - value to form the full 32-bit message code. The default value of - this keyword is: - - FacilityNames=( - System=0x0FF - Application=0xFFF - ) - - Facility codes occupy the low order 12 bits of the high order - 16-bits of a 32-bit message code. Any facility code that does not - fit in 12 bits is an error. This allows for 4,096 facility codes. - The first 256 codes are reserved for use by the system software. The - facility codes can be given symbolic names by following each value - with :name - - - The LanguageNames keyword defines the set of names that are allowed - as the value of the Language keyword in the message definition. The - set is delimited by left and right parentheses. Associated with each - language name is a number and a file name that are used to name the - generated resource file that contains the messages for that - language. The number corresponds to the language identifier to use - in the resource table. The number is separated from the file name - with a colon. - -LanguageNames=(English=0x409:MSG00409) -LanguageNames=(Japanese=0x411:MSG00411) - - Any new names in the source file which don't override the built-in - names are added to the list of valid languages. This allows an - application to support private languages with descriptive names. - - -------------------------------------------------------------------------- - MESSAGE DEFINITION SECTION - - Following the header section is the body of the Message Compiler - source file. The body consists of zero or more message definitions. - Each message definition begins with one or more of the following - statements: - - MessageId = [number|+number] - Severity = severity_name - Facility = facility_name - SymbolicName = name - - The MessageId statement marks the beginning of the message - definition. A MessageID statement is required for each message, - although the value is optional. If no value is specified, the value - used is the previous value for the facility plus one. If the value - is specified as +number then the value used is the previous value - for the facility, plus the number after the plus sign. Otherwise, if - a numeric value is given, that value is used. Any MessageId value - that does not fit in 16 bits is an error. - - The Severity and Facility statements are optional. These statements - specify additional bits to OR into the final 32-bit message code. If - not specified they default to the value last specified for a message - definition. The initial values prior to processing the first message - definition are: - - Severity=Success - Facility=Application - - The value associated with Severity and Facility must match one of - the names given in the FacilityNames and SeverityNames statements in - the header section. The SymbolicName statement allows you to - associate a C/C++ symbolic constant with the final 32-bit message - code. - */ -// -// -// DEFAULT MESSAGES -// ----------------- -// -// -// Values are 32 bit values layed out as follows: -// -// 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 -// 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 -// +---+-+-+-----------------------+-------------------------------+ -// |Sev|C|R| Facility | Code | -// +---+-+-+-----------------------+-------------------------------+ -// -// where -// -// Sev - is the severity code -// -// 00 - Success -// 01 - Informational -// 10 - Warning -// 11 - Error -// -// C - is the Customer code flag -// -// R - is a reserved bit -// -// Facility - is the facility code -// -// Code - is the facility's status code -// -// -// Define the facility codes -// -#define FACILITY_SYSTEM 0x0 -#define FACILITY_STUBS 0x3 -#define FACILITY_RUNTIME 0x2 -#define FACILITY_IO_ERROR_CODE 0x4 - - -// -// Define the severity codes -// -#define STATUS_SEVERITY_WARNING 0x2 -#define STATUS_SEVERITY_SUCCESS 0x0 -#define STATUS_SEVERITY_INFORMATIONAL 0x1 -#define STATUS_SEVERITY_ERROR 0x3 - - -// -// MessageId: MBG_ERROR -// -// MessageText: -// -// %1 -// -#define MBG_ERROR ((DWORD)0xE0001001L) - -// -// MessageId: MBG_WARNING -// -// MessageText: -// -// %1 -// -#define MBG_WARNING ((DWORD)0xA0001002L) - -// -// MessageId: MBG_INFO -// -// MessageText: -// -// %1 -// -#define MBG_INFO ((DWORD)0x60001003L) - -// -// -// DEVICE DRIVER MESSAGES -// ------------------------ -// -// NOTE: Changes of the codes below -// must match to the corresponding -// codes defined in -// pcpsdev.h or mbgerror.h !!!! -// -// MessageId: MBG_WINERR_STIME -// -// MessageText: -// -// %1Invalid date, time and status passed to the device. -// -#define MBG_WINERR_STIME ((DWORD)0xE0000001L) - -// -// MessageId: MBG_WINERR_CFG -// -// MessageText: -// -// %1Invalid or unknown parameters have been sent to the device. -// -#define MBG_WINERR_CFG ((DWORD)0xE0000002L) - -// -// MessageId: MBG_WINERR_GENERIC -// -// MessageText: -// -// %1Unknown device error occured. -// -#define MBG_WINERR_GENERIC ((DWORD)0xE0000013L) - -// -// MessageId: MBG_WINERR_PCPS_ERR_TIMEOUT -// -// MessageText: -// -// %1Timeout accessing the board. -// -#define MBG_WINERR_PCPS_ERR_TIMEOUT ((DWORD)0xE0000014L) - -// -// MessageId: MBG_WINERR_PCPS_ERR_FW_ID -// -// MessageText: -// -// %1Invalid firmware ID. -// -#define MBG_WINERR_PCPS_ERR_FW_ID ((DWORD)0xE0000015L) - -// -// MessageId: MBG_WINERR_PCPS_ERR_NBYTES -// -// MessageText: -// -// %1The number of parameter bytes passed to the board did not match the number of bytes expected. -// -#define MBG_WINERR_PCPS_ERR_NBYTES ((DWORD)0xE0000016L) - -// -// MessageId: MBG_WINERR_PCPS_ERR_INV_TIME -// -// MessageText: -// -// %1The board's time is not valid. -// -#define MBG_WINERR_PCPS_ERR_INV_TIME ((DWORD)0xE0000017L) - -// -// MessageId: MBG_WINERR_PCPS_ERR_FIFO -// -// MessageText: -// -// %1The board's FIFO is empty. -// -#define MBG_WINERR_PCPS_ERR_FIFO ((DWORD)0xE0000018L) - -// -// MessageId: MBG_WINERR_PCPS_ERR_NOT_READY -// -// MessageText: -// -// %1Board is temporary unable to respond (during initialization after RESET). -// -#define MBG_WINERR_PCPS_ERR_NOT_READY ((DWORD)0xE0000019L) - -// -// MessageId: MBG_WINERR_PCPS_ERR_INV_TYPE -// -// MessageText: -// -// %1Board did not recognize data type. -// -#define MBG_WINERR_PCPS_ERR_INV_TYPE ((DWORD)0xE000001AL) - -// -// MessageId: MBG_WINERR_NO_MEM -// -// MessageText: -// -// %1Failed to allocate memory. -// -#define MBG_WINERR_NO_MEM ((DWORD)0xE000001BL) - -// -// MessageId: MBG_WINERR_CLAIM_RSRC -// -// MessageText: -// -// %1Failed to claim port or memory resource. -// -#define MBG_WINERR_CLAIM_RSRC ((DWORD)0xE000001CL) - -// -// MessageId: MBG_WINERR_DEV_NOT_SUPP -// -// MessageText: -// -// %1The specified device is not supported by the driver. -// -#define MBG_WINERR_DEV_NOT_SUPP ((DWORD)0xE000001DL) - -// -// MessageId: MBG_WINERR_INV_DEVICE_REQUEST -// -// MessageText: -// -// %1The device request was invalid. -// -#define MBG_WINERR_INV_DEVICE_REQUEST ((DWORD)0xE000001EL) - -// -// MessageId: MBG_WINERR_NOT_IMPLEMENTED -// -// MessageText: -// -// %1The command or feature is not supported by this device. -// -#define MBG_WINERR_NOT_IMPLEMENTED ((DWORD)0xE000001FL) - -// -// MessageId: MBG_WINERR_USB_ACCESS -// -// MessageText: -// -// %1Timeout while trying to access the USB device. -// -#define MBG_WINERR_USB_ACCESS ((DWORD)0xE0000020L) - -// -// MessageId: MBG_WINERR_CYCLIC_TIMEOUT -// -// MessageText: -// -// %1Cyclic event (IRQ, etc.) did not occur. -// -#define MBG_WINERR_CYCLIC_TIMEOUT ((DWORD)0xE0000021L) - -// -// MessageId: MBG_WINERR_FUNC_NOT_SUPP_ON_OS -// -// MessageText: -// -// %1The function is not supported on this operating system. -// -#define MBG_WINERR_FUNC_NOT_SUPP_ON_OS ((DWORD)0xE0000022L) - -// -// MessageId: MBG_WINERR_LIB_NOT_COMPATIBLE -// -// MessageText: -// -// %1The installed version of the DLL is not compatible with version used to build the application. -// -#define MBG_WINERR_LIB_NOT_COMPATIBLE ((DWORD)0xE0000023L) - -// -// MessageId: MBG_WINERR_N_COM_EXCEEDS_SUPP -// -// MessageText: -// -// %1The number of COM ports provided by the device exceeds the maximum supported by the driver. -// -#define MBG_WINERR_N_COM_EXCEEDS_SUPP ((DWORD)0xE0000024L) - -// -// MessageId: MBG_WINERR_N_STR_EXCEEDS_SUPP -// -// MessageText: -// -// %1The number of string formats supported by the device exceeds the maximum supported by the driver. -// -#define MBG_WINERR_N_STR_EXCEEDS_SUPP ((DWORD)0xE0000025L) - -// -// MessageId: MBG_WINERR_IRQ_UNSAFE -// -// MessageText: -// -// %1The enabled IRQ is unsafe with this firmware/ASIC version. -// -#define MBG_WINERR_IRQ_UNSAFE ((DWORD)0xE0000026L) - - // - // - // MBGSVCTL Messages - // ----------------- - -// -// MessageId: MBG_WINERR_SVC_NOT_STARTED -// -// MessageText: -// -// %1 failed to be started.%r%rError:%2 -// -#define MBG_WINERR_SVC_NOT_STARTED ((DWORD)0xE0000100L) - -// -// MessageId: MBG_WINERR_SVC_NOT_STOPPED -// -// MessageText: -// -// %1 failed to be stopped.%r%rError:%2 -// -#define MBG_WINERR_SVC_NOT_STOPPED ((DWORD)0xE0000101L) - -// -// MessageId: MBG_WINERR_API_CALL_IN_FUNCTION -// -// MessageText: -// -// Failed to %1 in %2.%r%rError: %3 -// -#define MBG_WINERR_API_CALL_IN_FUNCTION ((DWORD)0xE0000102L) - -// -// MessageId: MBG_WINERR_SET_PRIORITY_CLASS -// -// MessageText: -// -// Failed to set Priority Class.%r%rError: %1 -// -#define MBG_WINERR_SET_PRIORITY_CLASS ((DWORD)0xE0000103L) - -// -// MessageId: MBG_WINERR_SET_THREAD_PRIORITY -// -// MessageText: -// -// Failed to set Thread Priority.%r%rError: %1 -// -#define MBG_WINERR_SET_THREAD_PRIORITY ((DWORD)0xE0000104L) - -// -// MessageId: MBG_WINERR_FAILED_CHECKING_ADMIN_RIGHTS -// -// MessageText: -// -// Failed to allocate %1 bytes of memory when checking admin rights. -// -#define MBG_WINERR_FAILED_CHECKING_ADMIN_RIGHTS ((DWORD)0xE0000105L) - -// -// MessageId: MBG_WINERR_WRITE_PARAMETER_TO_REGISTRY -// -// MessageText: -// -// Failed to write parameter to registry: "%1".%r%rError: %2 -// -#define MBG_WINERR_WRITE_PARAMETER_TO_REGISTRY ((DWORD)0xE0000106L) - -// -// MessageId: MBG_WARNING_READ_PARAMETER_FROM_REGISTRY -// -// MessageText: -// -// Failed to read parameter from registry: "%1".%r%rError: %2 -// -#define MBG_WARNING_READ_PARAMETER_FROM_REGISTRY ((DWORD)0xA0000107L) - -// -// MessageId: MBG_WINERR_OPEN_SC_MANAGER -// -// MessageText: -// -// Failed to open SC Manager. -// -#define MBG_WINERR_OPEN_SC_MANAGER ((DWORD)0xE0000108L) - -// -// MessageId: MBG_WINERR_QUERY_SERVICE_STATUS -// -// MessageText: -// -// Failed to query status of service %1.%r%rError: %2 -// -#define MBG_WINERR_QUERY_SERVICE_STATUS ((DWORD)0xE0000109L) - -// -// MessageId: MBG_WINERR_SVC_NOT_INSTALLED -// -// MessageText: -// -// %1 failed to be installed.%r%rError:%2 -// -#define MBG_WINERR_SVC_NOT_INSTALLED ((DWORD)0xE000010AL) - -// -// MessageId: MBG_WARNING_SVC_NOT_REMOVED -// -// MessageText: -// -// %1 failed to be removed.%r%rError:%2 -// -#define MBG_WARNING_SVC_NOT_REMOVED ((DWORD)0xA000010BL) - -// -// MessageId: MBG_WARNING_SVC_SET_AUTOSTART -// -// MessageText: -// -// Failed to set start type of service %1 to AUTO.%r%rError: %2 -// -#define MBG_WARNING_SVC_SET_AUTOSTART ((DWORD)0xA000010CL) - -// -// MessageId: MBG_WARNING_SVC_SET_START_MANUAL -// -// MessageText: -// -// Failed to set start type of service %1 to MANUALLY.%r%rError: %2 -// -#define MBG_WARNING_SVC_SET_START_MANUAL ((DWORD)0xA000010DL) - -// -// MessageId: MBG_WARNING_WRITE_SVC_DESCRIPTION -// -// MessageText: -// -// Failed to write description of time adjustment service.%r%rError: %1 -// -#define MBG_WARNING_WRITE_SVC_DESCRIPTION ((DWORD)0xA000010EL) - -// -// MessageId: MBG_WINERR_TIME_GET_DEV_CAPS -// -// MessageText: -// -// Function timeGetDevCaps() failed. -// -#define MBG_WINERR_TIME_GET_DEV_CAPS ((DWORD)0xE000010FL) - -// -// MessageId: MBG_WINERR_QUERY_PERFORMANCE_FREQUENCY -// -// MessageText: -// -// Function QueryPerformanceFrequency() failed. -// -#define MBG_WINERR_QUERY_PERFORMANCE_FREQUENCY ((DWORD)0xE0000110L) - -// -// MessageId: MBG_WARNING_FAILED_TO_OPEN_REG_KEY_ADJTM_CFG -// -// MessageText: -// -// Failed to open registry key %1 while getting adjust time cfg.%r%rError: %2 -// -#define MBG_WARNING_FAILED_TO_OPEN_REG_KEY_ADJTM_CFG ((DWORD)0xA0000111L) - -// -// MessageId: MBG_WARNING_FAILED_TO_OPEN_REG_KEY_SERIAL_CFG -// -// MessageText: -// -// Failed to open registry key %1 while getting serial device cfg.%r%rError: %2 -// -#define MBG_WARNING_FAILED_TO_OPEN_REG_KEY_SERIAL_CFG ((DWORD)0xA0000112L) - -// -// MessageId: MBG_WARNING_FAILED_TO_OPEN_REG_KEY_COUNTRY_CODE -// -// MessageText: -// -// Failed to open registry key %1 while getting country code.%r%rError: %2 -// -#define MBG_WARNING_FAILED_TO_OPEN_REG_KEY_COUNTRY_CODE ((DWORD)0xA0000113L) - -// -// MessageId: MBG_WARNING_FAILED_TO_OPEN_REG_KEY_INF_PATH -// -// MessageText: -// -// Failed to open registry key %1 while getting inf path.%r%rError: %2 -// -#define MBG_WARNING_FAILED_TO_OPEN_REG_KEY_INF_PATH ((DWORD)0xA0000114L) - -// -// MessageId: MBG_WARNING_FAILED_TO_OPEN_REG_KEY_DEVICE -// -// MessageText: -// -// Failed to open registry key for device calling %1.%r%rError: %2 -// -#define MBG_WARNING_FAILED_TO_OPEN_REG_KEY_DEVICE ((DWORD)0xE0000115L) - -// -// MessageId: MBG_WARNING_FAILED_TO_CREATE_REG_KEY_ADJTM_CFG -// -// MessageText: -// -// Failed to create registry key %1 when writing time service configuration.%r%rError: %2 -// -#define MBG_WARNING_FAILED_TO_CREATE_REG_KEY_ADJTM_CFG ((DWORD)0xE0000116L) - -// -// MessageId: MBG_WARNING_FAILED_TO_CREATE_REG_KEY_SERIAL_CFG -// -// MessageText: -// -// Failed to create registry key %1 when writing serial device configuration.%r%rError: %2 -// -#define MBG_WARNING_FAILED_TO_CREATE_REG_KEY_SERIAL_CFG ((DWORD)0xE0000117L) - -// -// MessageId: MBG_WARNING_FAILED_TO_CREATE_REG_KEY -// -// MessageText: -// -// Failed to create registry key %1.%r%rError: %2 -// -#define MBG_WARNING_FAILED_TO_CREATE_REG_KEY ((DWORD)0xE0000118L) - -// -// MessageId: MBG_WARNING_FAILED_TO_CREATE_REG_KEY_COUNTRY_CODE -// -// MessageText: -// -// Failed to create registry key %1 when writing country code.%r%rError: %2 -// -#define MBG_WARNING_FAILED_TO_CREATE_REG_KEY_COUNTRY_CODE ((DWORD)0xE0000119L) - -// -// MessageId: MBG_WARNING_FAILED_TO_CREATE_REG_KEY_ISA_PORTS -// -// MessageText: -// -// Failed to create registry key %1 when writing isa ports.%r%rError: %2 -// -#define MBG_WARNING_FAILED_TO_CREATE_REG_KEY_ISA_PORTS ((DWORD)0xE000011AL) - -// -// -// SERVICE MESSAGES -// ---------------- -// -// -// MessageId: MBG_INFO_SVC_STARTING -// -// MessageText: -// -// %1 starting.%r%r%2. -// -#define MBG_INFO_SVC_STARTING ((DWORD)0x60000200L) - -// -// MessageId: MBG_INFO_LOG_TIME_ADJUSTMENT_DATA_TO_FILE -// -// MessageText: -// -// Logging time adjustment data to file:%r%1 -// -#define MBG_INFO_LOG_TIME_ADJUSTMENT_DATA_TO_FILE ((DWORD)0x60000201L) - -// -// MessageId: MBG_INFO_LEAP_SECOND_ANNOUNCEMENT -// -// MessageText: -// -// %1%2Leap second announcement detected. -// -#define MBG_INFO_LEAP_SECOND_ANNOUNCEMENT ((DWORD)0x60000202L) - -// -// MessageId: MBG_INFO_LEAP_SECOND_INSERTED -// -// MessageText: -// -// %1%2Leap second inserted. -// -#define MBG_INFO_LEAP_SECOND_INSERTED ((DWORD)0x60000203L) - -// -// MessageId: MBG_WARNING_TIME_SERVICE_STOPPED -// -// MessageText: -// -// Time adjustment service stopped. -// -#define MBG_WARNING_TIME_SERVICE_STOPPED ((DWORD)0xA0000204L) - -// -// MessageId: MBG_WINERR_TIME_DIFF_EXCEEDS_LIMIT -// -// MessageText: -// -// Time difference %1 s exceeds limit %2 s. -// -#define MBG_WINERR_TIME_DIFF_EXCEEDS_LIMIT ((DWORD)0xE0000205L) - -// -// MessageId: MBG_WARNING_TIME_ADJUSTMENT_DISABLED -// -// MessageText: -// -// System time adjustment has been found disabled. -// -#define MBG_WARNING_TIME_ADJUSTMENT_DISABLED ((DWORD)0xA0000206L) - -// -// MessageId: MBG_WARNING_TIME_ADJUSTMENT_MODIFIED_BY_ANOTHER_PROGRAM -// -// MessageText: -// -// System time adjustment has been modified by another program: %1. -// -#define MBG_WARNING_TIME_ADJUSTMENT_MODIFIED_BY_ANOTHER_PROGRAM ((DWORD)0xA0000207L) - -// -// MessageId: MBG_WARNING_CLOCK_INCONSISTENCY_DETECTED -// -// MessageText: -// -// Clock inconsistency detected: %r%1. -// -#define MBG_WARNING_CLOCK_INCONSISTENCY_DETECTED ((DWORD)0xA0000208L) - -// -// MessageId: MBG_WARNING_NEW_SYSTEM_TIME -// -// MessageText: -// -// New system time. -// -#define MBG_WARNING_NEW_SYSTEM_TIME ((DWORD)0xA0000209L) - -// -// MessageId: MBG_WINERR_REF_CLOCK_FAILURE_DETECTED -// -// MessageText: -// -// Ref clock failure detected at: %1. -// -#define MBG_WINERR_REF_CLOCK_FAILURE_DETECTED ((DWORD)0xE000020AL) - -// -// MessageId: MBG_INFO_REF_CLOCK_FAILURE_ENDED -// -// MessageText: -// -// Ref clock failure ended at: %1. -// -#define MBG_INFO_REF_CLOCK_FAILURE_ENDED ((DWORD)0x6000020BL) - -// -// MessageId: MBG_WINERR_REF_CLOCK_FAILURE_NOTIFICATION -// -// MessageText: -// -// Ref clock failure persisting for %1. -// -#define MBG_WINERR_REF_CLOCK_FAILURE_NOTIFICATION ((DWORD)0xE000020CL) - -// -// MessageId: MBG_WINERR_REF_CLOCK_FAILURE_NOTIFICATION_MORE -// -// MessageText: -// -// Ref clock failure persisting for more than %1. -// -#define MBG_WINERR_REF_CLOCK_FAILURE_NOTIFICATION_MORE ((DWORD)0xE000020DL) - -// -// MessageId: MBG_INFO_CURRENT_REF_TIME -// -// MessageText: -// -// Current reference time: %1. -// -#define MBG_INFO_CURRENT_REF_TIME ((DWORD)0x6000020EL) - -// -// MessageId: MBG_WINERR_CURRENT_REF_TIME -// -// MessageText: -// -// Current reference time: %1. -// -#define MBG_WINERR_CURRENT_REF_TIME ((DWORD)0xE000020FL) - -// -// MessageId: MBG_WARNING_SET_LOCAL_TIME -// -// MessageText: -// -// Setting system local time to: %1. -// -#define MBG_WARNING_SET_LOCAL_TIME ((DWORD)0xA0000210L) - -// -// MessageId: MBG_WARNING_SET_SYSTEM_TIME -// -// MessageText: -// -// Setting system time to: %1. -// -#define MBG_WARNING_SET_SYSTEM_TIME ((DWORD)0xA0000211L) - -// -// MessageId: MBG_WARNING_REF_TIME_INVALID -// -// MessageText: -// -// %1%2Reference time is invalid. -// -#define MBG_WARNING_REF_TIME_INVALID ((DWORD)0xA0000212L) - -// -// MessageId: MBG_WARNING_REF_TIME_SET_MANUAL -// -// MessageText: -// -// %1%2Reference time has been set manually. -// -#define MBG_WARNING_REF_TIME_SET_MANUAL ((DWORD)0xA0000213L) - -// -// MessageId: MBG_INFO_REF_CLOCK_SYNCED -// -// MessageText: -// -// %1%2Reference time source is synchronized -// -#define MBG_INFO_REF_CLOCK_SYNCED ((DWORD)0x60000214L) - -// -// MessageId: MBG_WARNING_REF_CLOCK_NOT_SYNCED -// -// MessageText: -// -// %1%2Reference time source not synchronized. -// -#define MBG_WARNING_REF_CLOCK_NOT_SYNCED ((DWORD)0xA0000215L) - -// -// MessageId: MBG_WARNING_TIME_ADJUSTMENT_DEFAULT_SETTINGS -// -// MessageText: -// -// One or more settings for the time adjustment service have been set to default values. -// -#define MBG_WARNING_TIME_ADJUSTMENT_DEFAULT_SETTINGS ((DWORD)0xA0000216L) - -// -// MessageId: MBG_WARNING_SERIAL_STRING_DEFAULT_SETTINGS -// -// MessageText: -// -// One or more settings for the serial time string have been set to default values. -// -#define MBG_WARNING_SERIAL_STRING_DEFAULT_SETTINGS ((DWORD)0xA0000217L) - -// -// MessageId: MBG_INFO_SERVICE_PARAMETERS_CHANGED -// -// MessageText: -// -// Time adjustment service parameters have been changed:%r%r%1 -// -#define MBG_INFO_SERVICE_PARAMETERS_CHANGED ((DWORD)0x60000218L) - -// -// MessageId: MBG_INFO_TIME_ADJUSTMENT_IN_RANGE -// -// MessageText: -// -// Time adjustment in range: %1 s. -// -#define MBG_INFO_TIME_ADJUSTMENT_IN_RANGE ((DWORD)0x60000219L) - -// -// MessageId: MBG_WARNING_TIME_ADJUSTMENT_OUT_OF_RANGE -// -// MessageText: -// -// Time adjustment out of range: %1. -// -#define MBG_WARNING_TIME_ADJUSTMENT_OUT_OF_RANGE ((DWORD)0xA000021AL) - -// -// MessageId: MBG_WINERR_ERROR_OPEN_DEVICE -// -// MessageText: -// -// Failed to open device "%1". -// -#define MBG_WINERR_ERROR_OPEN_DEVICE ((DWORD)0xE000021BL) - -// -// MessageId: MBG_WARNING_READ_DEVICE_INFO -// -// MessageText: -// -// Failed to read device info from device "%1". -// -#define MBG_WARNING_READ_DEVICE_INFO ((DWORD)0xA000021CL) - -// -// MessageId: MBG_WARNING_REF_CLOCK_CHANGED -// -// MessageText: -// -// Reference time source has been changed:%r%1 -// -#define MBG_WARNING_REF_CLOCK_CHANGED ((DWORD)0xA000021DL) - -// -// MessageId: MBG_WINERR_FAILED_OPEN_SERIAL_PORT -// -// MessageText: -// -// Failed to open serial port %1 -// -#define MBG_WINERR_FAILED_OPEN_SERIAL_PORT ((DWORD)0xE000021EL) - -// -// MessageId: MBG_INFO_SUCCEEDED_OPEN_SERIAL_PORT -// -// MessageText: -// -// Now succeeded to open serial port %1 -// -#define MBG_INFO_SUCCEEDED_OPEN_SERIAL_PORT ((DWORD)0x6000021FL) - -// -// MessageId: MBG_WARNING_TIMEOUT_RECEIVING_SERIAL_STRING -// -// MessageText: -// -// Timeout receiving %1. -// -#define MBG_WARNING_TIMEOUT_RECEIVING_SERIAL_STRING ((DWORD)0xA0000220L) - -// -// MessageId: MBG_INFO_SUCCESSFULLY_RECEIVING_SERIAL_STRING -// -// MessageText: -// -// Successfully receiving %1. -// -#define MBG_INFO_SUCCESSFULLY_RECEIVING_SERIAL_STRING ((DWORD)0x60000221L) - -// -// MessageId: MBG_WINERR_DEVICE_REMOVED -// -// MessageText: -// -// Error reading from device driver.%rThe device "%1" was obviously disconnected from the PC. The system time adjustment has been set to the standard value. -// -#define MBG_WINERR_DEVICE_REMOVED ((DWORD)0xE0000222L) - -// -// MessageId: MBG_INFO_DEVICE_RECONNECTED -// -// MessageText: -// -// The device "%1" has been reattached to the PC and is used by the time adjustment service. -// -#define MBG_INFO_DEVICE_RECONNECTED ((DWORD)0x60000223L) - -// -// MessageId: MBG_WINERR_SVC_INVALID_TIME -// -// MessageText: -// -// Invalid time read from the device:%r%1. -// -#define MBG_WINERR_SVC_INVALID_TIME ((DWORD)0xE0000224L) - -// -// MessageId: MBG_WARNING_SVC_STARTING -// -// MessageText: -// -// %1 starting.%r%r%2. -// -#define MBG_WARNING_SVC_STARTING ((DWORD)0xA0000225L) - -// -// MessageId: MBG_WARNING_TIME_SERVICE_PAUSED -// -// MessageText: -// -// Time adjustment service paused. -// -#define MBG_WARNING_TIME_SERVICE_PAUSED ((DWORD)0xA0000226L) - -// -// MessageId: MBG_INFO_TIME_SERVICE_CONTINUED -// -// MessageText: -// -// Time adjustment service continued. -// -#define MBG_INFO_TIME_SERVICE_CONTINUED ((DWORD)0x60000227L) - -// -// MessageId: MBG_INFO_SERIAL_PORT_OPENED_IN_NORMAL_MODE -// -// MessageText: -// -// Serial port opened in normal mode. -// -#define MBG_INFO_SERIAL_PORT_OPENED_IN_NORMAL_MODE ((DWORD)0x60000228L) - -// -// MessageId: MBG_INFO_EXECUTE_CMD_SUCCEEDED -// -// MessageText: -// -// The command %"%1%" was executed. -// -#define MBG_INFO_EXECUTE_CMD_SUCCEEDED ((DWORD)0x60000229L) - -// -// MessageId: MBG_WINERR_EXECUTE_CMD_FAILED -// -// MessageText: -// -// Failed to execute the command %"%1%".%r%rError: %2 -// -#define MBG_WINERR_EXECUTE_CMD_FAILED ((DWORD)0xE000022AL) - -// -// MessageId: MBG_WINERR_REF_CLOCK_STEPPED -// -// MessageText: -// -// The reference time stepped! The time adjustment is pausing.%r%rCurrent reference time: %1 -// -#define MBG_WINERR_REF_CLOCK_STEPPED ((DWORD)0xA000022BL) - -// -// MessageId: MBG_INFO_REF_CLOCK_STEP_END -// -// MessageText: -// -// The reference time stepped back into the correct range. The time adjustment continues.%r%rCurrent reference time: %1 -// -#define MBG_INFO_REF_CLOCK_STEP_END ((DWORD)0x6000022CL) - -// -// MessageId: MBG_WARNING_TIMESCALE_CHANGED -// -// MessageText: -// -// The time scale of the reference clock changed from "%1" to "%2". -// -#define MBG_WARNING_TIMESCALE_CHANGED ((DWORD)0xA000022DL) - -// -// MessageId: MBG_INFO_TIMESCALE_CONFIG -// -// MessageText: -// -// The time scale of the reference clock is configured to "%1". -// -#define MBG_INFO_TIMESCALE_CONFIG ((DWORD)0x6000022EL) - -// -// MessageId: MBG_INFO_GPS_MODE_CHANGED -// -// MessageText: -// -// The GPS receiver switched to "%1". -// -#define MBG_INFO_GPS_MODE_CHANGED ((DWORD)0x6000022FL) - -// -// MessageId: MBG_INFO_GPS_ANT_CONNECTED -// -// MessageText: -// -// The GPS antenna is connected to the receiver. -// -#define MBG_INFO_GPS_ANT_CONNECTED ((DWORD)0x60000230L) - -// -// MessageId: MBG_WARNING_GPS_ANT_FAULTY -// -// MessageText: -// -// The GPS receiver reports "Antenna Faulty". -// -#define MBG_WARNING_GPS_ANT_FAULTY ((DWORD)0xA0000231L) - diff --git a/c/mbglib/include/pci_asic.h b/c/mbglib/include/pci_asic.h index cdbc995..5a3e3d2 100644 --- a/c/mbglib/include/pci_asic.h +++ b/c/mbglib/include/pci_asic.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pci_asic.h 1.24 2013/10/01 15:29:39Z martin REL_M $ + * $Id: pci_asic.h 1.31 2018/06/25 12:32:19Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,22 @@ * * ----------------------------------------------------------------------- * $Log: pci_asic.h $ - * Revision 1.24 2013/10/01 15:29:39Z martin + * Revision 1.31 2018/06/25 12:32:19Z martin + * Added PCPS_ASIC_STR_FMT format specifier. + * Revision 1.30 2018/03/27 12:39:46 martin + * Updated minor version for PZF180PEX to 0x01. + * Revision 1.29 2017/07/04 14:18:03 martin + * Updated minor version for PTP270PEX. + * Revision 1.28 2017/05/10 15:24:21 martin + * Tiny cleanup. + * Revision 1.27 2017/04/25 11:36:30 martin + * Renamed GRC181PEX to GNS181PEX. + * Revision 1.26 2016/09/15 14:55:02 martin + * Support GRC181PEX. + * Added doxgen comments. + * Revision 1.25 2014/10/17 11:38:39 martin + * Updated version info for GPS180PEX. + * Revision 1.24 2013/10/01 15:29:39 martin * Updated version info for PTP270PEX. * Revision 1.23 2013/06/26 15:57:07Z martin * Support GLN180PEX. @@ -40,7 +55,7 @@ * Modified syntax of macro _convert_asic_version_number(). * Added macros to deal with the ASIC version number. * Added definition PCI_ASIC_HAS_PGMB_IRQ. - * Added ASIC revision numbers for PEX511, TCR511PEX, and GPS170PEX + * Added ASIC revision numbers for PEX511, TCR511PEX, and GPS170PEX * which fix an IRQ bug with these cards. * Added definitions for PTP270PEX, FRC511PEX, and TCR170PEX. * Revision 1.12 2008/07/21 10:30:00Z martin @@ -66,7 +81,7 @@ * Revision 1.4 2004/10/14 15:01:23 martin * Added support for TCR167PCI. * Revision 1.3 2003/05/13 14:38:55Z MARTIN - * Added ushort fields to unions PCI_ASIC_REG and + * Added ushort fields to unions PCI_ASIC_REG and * PCI_ASIC_ADDON_DATA. * Revision 1.2 2003/04/03 10:56:38 martin * Use unions for registers. @@ -100,77 +115,145 @@ #define _USING_BYTE_ALIGNMENT #endif +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Set of PCI ASIC registers which are writeable once after power-up + **/ typedef struct { uint32_t cfg_class_rev_id; uint16_t cfg_badr_0; uint16_t cfg_dev_id; + } PCI_ASIC_CFG; +/** + * @brief A PCI ASIC register as 32, 16, or 8 bit accessible union + */ typedef union { uint32_t ul; uint16_t us[2]; uint8_t b[4]; + } PCI_ASIC_REG; + +/** + * @brief A data type to hold the PCI ASIC version code + */ typedef uint32_t PCI_ASIC_VERSION; + #define _mbg_swab_asic_version( _p ) _mbg_swab32( _p ) + + +/** + * @brief A data type to hold the PCI ASIC feature flags mask + * + * @see @ref PCI_ASIC_FEATURE_MASKS + */ typedef uint32_t PCI_ASIC_FEATURES; + #define _mbg_swab_asic_features( _p ) _mbg_swab32( _p ) -#define PCI_ASIC_HAS_MM_IO 0x0001 -#define PCI_ASIC_HAS_PGMB_IRQ 0x0002 +/** + * @brief Bit masks used with ::PCI_ASIC_FEATURES + * + * @see ::PCI_ASIC_FEATURES + * + * @anchor PCI_ASIC_FEATURE_MASKS @{ */ + +#define PCI_ASIC_HAS_MM_IO 0x0001 ///< The device supports memory mapped I/O +#define PCI_ASIC_HAS_PGMB_IRQ 0x0002 ///< The device supports programmable interrupts (yet not used) + +/** @} anchor PCI_ASIC_FEATURE_MASKS */ + + + +/** + * @brief The addon-data part of a PCI ASIC + */ typedef union { uint32_t ul[4]; uint16_t us[8]; uint8_t b[16]; + } PCI_ASIC_ADDON_DATA; + +/** + * @brief Register layout of a PCI ASIC + */ typedef struct { - PCI_ASIC_CFG cfg; // writeable from add-on once after power-up - PCI_ASIC_VERSION raw_version; - PCI_ASIC_FEATURES features; - PCI_ASIC_REG status_port; - PCI_ASIC_REG control_status; // codes defined below - PCI_ASIC_REG pci_data; // pass byte from PCI bus to add-on - PCI_ASIC_REG reserved_1; - - PCI_ASIC_ADDON_DATA addon_data; // returns data from add-on to PCI bus - PCI_ASIC_ADDON_DATA reserved_2; // currently not implemented + PCI_ASIC_CFG cfg; ///< Registers which are writeable from add-on once after power-up + PCI_ASIC_VERSION raw_version; ///< Raw version code + PCI_ASIC_FEATURES features; ///< PCI ASIC feature mask, see @ref PCI_ASIC_FEATURE_MASKS + PCI_ASIC_REG status_port; ///< The status port register + PCI_ASIC_REG control_status; ///< See @ref PCI_ASIC_CONTROL_STATUS_MASKS + PCI_ASIC_REG pci_data; ///< Register used to pass byte from PCI bus to add-on side + PCI_ASIC_REG reserved_1; ///< Currently not implemented / used + + PCI_ASIC_ADDON_DATA addon_data; ///< Register set used to return data from add-on to PCI bus + PCI_ASIC_ADDON_DATA reserved_2; ///< Currently not implemented / used + } PCI_ASIC; -// The following bits are used with the control_status register. -// All other bits are reserved for future use. -// The IRQ flag for the add-on side is set whenever data is -// written to the cmd register. It is cleared if the add-on -// microcontroller writes this bit back to the control_status -// register. If the bit is set, the add-on signals /ADD_ON_IRQ -// and ADD_ON_BUSY are asserted. +/** + * @brief Bit masks used with ::PCI_ASIC::control_status + * + * @see ::PCI_ASIC + * + * @anchor PCI_ASIC_CONTROL_STATUS_MASKS @{ */ + +/** + * @brief Add-on IRQ flag + * + * The IRQ flag for the add-on side is set whenever data is + * written to the cmd register. It is cleared if the add-on + * microcontroller writes this bit back to the control_status + * register. If the bit is set, the add-on signals /ADD_ON_IRQ + * and ADD_ON_BUSY are asserted. + */ #define PCI_ASIC_ADD_ON_IRQF 0x00000001UL -// The IRQ flag for the PCI bus is set whenever the add-on -// microcontroller asserts the ASIC's /PCI_IRQ line, or the -// add-on microcontroller sets this bit to 1. It is cleared -// if this bit is written back from the PCI side. If the bit -// is set, an IRQ is asserted on the PCI bus. +/** + * @brief PCI IRQ flag + * + * The IRQ flag for the PCI bus is set whenever the add-on + * microcontroller asserts the ASIC's /PCI_IRQ line, or the + * add-on microcontroller sets this bit to 1. It is cleared + * if this bit is written back from the PCI side. If the bit + * is set, an IRQ is asserted on the PCI bus. + */ #define PCI_ASIC_PCI_IRQF 0x00010000UL +// NOTE All other bits are reserved for future use. + +/** @} anchor PCI_ASIC_CONTROL_STATUS_MASKS */ + -// The ASIC's address decoder always decodes 8 bits, so -// each device must request at least that number of -// addresses from the PCI BIOS: + +/** + * @brief PCI address range + * + * The ASIC's address decoder always decodes 8 bits, so + * each device must request at least this number of + * addresses from the PCI BIOS. + */ #define PCI_ASIC_ADDR_RANGE 0x100U @@ -229,34 +312,44 @@ typedef struct _hilo_16( PCI_DEV_TCR511PCI ) \ } -/* - Handling of the version numbers of the PCI interface - chips has changed between the ASICs used for standard PCI - and the EPLDs used to configure the PEX8311 chip - for a specific device. - The macro below can be used to convert both types - of version number into the same format so that the - version numbers can be handled in the same way: -*/ + +/** + * @brief Version number conversion macro + * + * Handling of the version numbers of the PCI interface + * chips has changed between the ASICs used for standard PCI + * and the EPLDs used to configure the PEX8311 chip + * for a specific device. + * + * This macro can be used to convert both types of + * version number into the same format so that the + * version numbers can be handled in the same way + */ #define _convert_asic_version_number( _n ) \ ( ( (_n) < 0x100 ) ? ( (_n) << 8 ) : (_n) ) -/* - * Macros to extract the major and minor part of an ASIC version number */ +#define PCPS_ASIC_STR_FMT "%u.%02X" // TODO Or should this be "%u.%02u" +/** + * @brief Extract the major part of an ASIC version number + */ #define _pcps_asic_version_major( _v ) \ ( ( (_v) >> 8 ) & 0xFF ) + +/** + * @brief Extract the minor part of an ASIC version number + */ #define _pcps_asic_version_minor( _v ) \ ( (_v) & 0xFF ) -/* - * Macros to check whether a version number is correct - * and matches a required minimum version + +/** + * @brief Check whether a version number is correct and matches a required minimum version */ #define _pcps_asic_version_greater_equal( _v, _v_major, _v_minor ) \ ( \ @@ -265,93 +358,126 @@ typedef struct ) -/* - The low byte of the converted version number is handled - as a minor version, whereas the remaining upper bytes are - interpreted as a major number which may be specific - for a device. -*/ -enum + +/** + * @brief ASIC major version numbers + * + * @see @ref PCI_ASIC_MINOR_VERSION_NUMBERS + */ +enum PCI_ASIC_MAJOR_VERSION_NUMBERS { - PCI_ASIC_MAJOR_PCI_0, // PCI ASIC with CRC bug - PCI_ASIC_MAJOR_PCI_1, // fixed version of PCI ASIC - PCI_ASIC_MAJOR_PEX511, // PEX EPLD for PEX511 - PCI_ASIC_MAJOR_GPS170PEX, // PEX EPLD for GPS170PEX - PCI_ASIC_MAJOR_TCR511PEX, // PEX EPLD for TCR511PEX - PCI_ASIC_MAJOR_PTP270PEX, // PEX EPLD for PTP270PEX - PCI_ASIC_MAJOR_FRC511PEX, // PEX EPLD for FRC511PEX - PCI_ASIC_MAJOR_TCR170PEX, // PEX EPLD for TCR170PEX - PCI_ASIC_MAJOR_GPS180PEX, // PEX EPLD for GPS180PEX - PCI_ASIC_MAJOR_TCR180PEX, // PEX EPLD for TCR180PEX - PCI_ASIC_MAJOR_PZF180PEX, // PEX EPLD for PZF180PEX - PCI_ASIC_MAJOR_GLN180PEX, // PEX EPLD for GLN180PEX - N_PCI_ASIC_MAJOR // the number of known codes + PCI_ASIC_MAJOR_PCI_0, ///< PCI ASIC with CRC bug + PCI_ASIC_MAJOR_PCI_1, ///< fixed version of PCI ASIC + PCI_ASIC_MAJOR_PEX511, ///< PEX EPLD for PEX511 + PCI_ASIC_MAJOR_GPS170PEX, ///< PEX EPLD for GPS170PEX + PCI_ASIC_MAJOR_TCR511PEX, ///< PEX EPLD for TCR511PEX + PCI_ASIC_MAJOR_PTP270PEX, ///< PEX EPLD for PTP270PEX + PCI_ASIC_MAJOR_FRC511PEX, ///< PEX EPLD for FRC511PEX + PCI_ASIC_MAJOR_TCR170PEX, ///< PEX EPLD for TCR170PEX + PCI_ASIC_MAJOR_GPS180PEX, ///< PEX EPLD for GPS180PEX/GPS180AMC + PCI_ASIC_MAJOR_TCR180PEX, ///< PEX EPLD for TCR180PEX + PCI_ASIC_MAJOR_PZF180PEX, ///< PEX EPLD for PZF180PEX + PCI_ASIC_MAJOR_GLN180PEX, ///< PEX EPLD for GLN180PEX + PCI_ASIC_MAJOR_GNS181PEX, ///< PEX EPLD for GNS181PEX + N_PCI_ASIC_MAJOR ///< the number of known codes }; -/* - The minor number increases when a new EPLD image is released. - At least EPLD images with the following "required minor" numbers - should be installed for proper operation. The "current minor" - numbers can be used to check if a newer EPLD image is available: -*/ + + +/** + * @brief ASIC minor version definitions + * + * The minor number increases when a new EPLD image is released. + * At least EPLD images with the defined "required minor" numbers + * should be installed for proper operation. The "current minor" + * numbers can be used to check if a newer EPLD image is available. + * + * @see ::PCI_ASIC_MAJOR_VERSION_NUMBERS + * + * @anchor PCI_ASIC_MINOR_VERSION_NUMBERS @{ */ + #define PCI_ASIC_CURRENT_MINOR_PEX511 0x04 #define PCI_ASIC_REQUIRED_MINOR_PEX511 0x03 -#define PCI_ASIC_FIX_HRT_MINOR_PEX511 0x04 // increases HRT accuracy -#define PCI_ASIC_FIX_IRQ_MINOR_PEX511 0x03 // fixes IRQ problem -#define PCI_ASIC_HR_TIME_MINOR_PEX511 0x02 // supports HR time with PEX511 +#define PCI_ASIC_FIX_HRT_MINOR_PEX511 0x04 // Increases HRT accuracy +#define PCI_ASIC_FIX_IRQ_MINOR_PEX511 0x03 // Fixes IRQ problem +#define PCI_ASIC_HR_TIME_MINOR_PEX511 0x02 // Supports HR time with PEX511 #define PCI_ASIC_CURRENT_MINOR_GPS170PEX 0x05 #define PCI_ASIC_REQUIRED_MINOR_GPS170PEX 0x03 -#define PCI_ASIC_ENH_HRT_MINOR_GPS170PEX 0x05 // enhanced MM HRT accuracy -#define PCI_ASIC_FIX_HRT_MINOR_GPS170PEX 0x04 // increases MM HRT accuracy -#define PCI_ASIC_FIX_IRQ_MINOR_GPS170PEX 0x03 // fixes IRQ problem +#define PCI_ASIC_ENH_HRT_MINOR_GPS170PEX 0x05 // Enhanced MM HRT accuracy +#define PCI_ASIC_FIX_HRT_MINOR_GPS170PEX 0x04 // Increases MM HRT accuracy +#define PCI_ASIC_FIX_IRQ_MINOR_GPS170PEX 0x03 // Fixes IRQ problem #define PCI_ASIC_CURRENT_MINOR_TCR511PEX 0x04 #define PCI_ASIC_REQUIRED_MINOR_TCR511PEX 0x03 // 0x04 // EPLD sources shared with PEX511 0x04 -#define PCI_ASIC_FIX_IRQ_MINOR_TCR511PEX 0x03 // fixes IRQ problem, increases HRT accuracy +#define PCI_ASIC_FIX_IRQ_MINOR_TCR511PEX 0x03 // Fixes IRQ problem, increases HRT accuracy -#define PCI_ASIC_CURRENT_MINOR_PTP270PEX 0x05 +#define PCI_ASIC_CURRENT_MINOR_PTP270PEX 0x06 #define PCI_ASIC_REQUIRED_MINOR_PTP270PEX 0x01 +// 0x06 // Supports 1 PPS pulse shift // 0x05 // ... // 0x04 // ... // 0x03 // ... -// 0x02 // increased accuracy of IRIG DCLS slopes -// 0x01 // supports inversion of ucap slopes +// 0x02 // Increased accuracy of IRIG DCLS slopes +// 0x01 // Supports inversion of ucap slopes #define PCI_ASIC_CURRENT_MINOR_FRC511PEX 0x01 #define PCI_ASIC_REQUIRED_MINOR_FRC511PEX 0x01 #define PCI_ASIC_CURRENT_MINOR_TCR170PEX 0x03 #define PCI_ASIC_REQUIRED_MINOR_TCR170PEX 0x02 -#define PCI_ASIC_FIX_EE_ACCESS_TCR170PEX 0x02 // fixes EE access problem after reset -#define PCI_ASIC_FIX_FO_IN_LEVEL_TCR170PEX 0x03 // correct polarity for fiber optic input +#define PCI_ASIC_FIX_EE_ACCESS_TCR170PEX 0x02 // Fixes EE access problem after reset +#define PCI_ASIC_FIX_FO_IN_LEVEL_TCR170PEX 0x03 // Correct polarity for fiber optic input -#define PCI_ASIC_CURRENT_MINOR_GPS180PEX 0x05 +#define PCI_ASIC_CURRENT_MINOR_GPS180PEX 0x06 #define PCI_ASIC_REQUIRED_MINOR_GPS180PEX 0x01 -// 0x01 // updated VHDL compiler and associated PCI primitives +// 0x01 // Updated VHDL compiler and associated PCI primitives // 0x02 // I/O using 3.3V LVTTL // 0x03 // GPS TIC pulse len now 1 sample clock // 0x04 // Enabled PCI IRQ line which had unintentionally been disabled earlier // 0x05 // Increased accuracy of synthesizer output +// 0x06 // T0 AUX Capture used by firmware v2.0x #define PCI_ASIC_CURRENT_MINOR_TCR180PEX 0x00 #define PCI_ASIC_REQUIRED_MINOR_TCR180PEX 0x00 -#define PCI_ASIC_CURRENT_MINOR_PZF180PEX 0x00 +#define PCI_ASIC_CURRENT_MINOR_PZF180PEX 0x01 #define PCI_ASIC_REQUIRED_MINOR_PZF180PEX 0x00 +// 0x01 // ... #define PCI_ASIC_CURRENT_MINOR_GLN180PEX 0x00 #define PCI_ASIC_REQUIRED_MINOR_GLN180PEX 0x00 +#define PCI_ASIC_CURRENT_MINOR_GNS181PEX 0x00 +#define PCI_ASIC_REQUIRED_MINOR_GNS181PEX 0x00 + +/** @} anchor PCI_ASIC_MINOR_VERSION_NUMBERS */ + + + +/** + * @brief A structure holding version information for a specific device + * + * @see ::DEFAULT_PCI_ASIC_VERSION_INFO_TABLE + */ typedef struct { unsigned int dev_type_num; unsigned int major; unsigned int current_minor; unsigned int required_minor; + } PCI_ASIC_VERSION_INFO; + +/** + * @brief An initializer for a table of ASIC version information for all known devices + * + * @note GPS180AMC uses the same ASIC as GPS180PEX + * + * @see ::PCI_ASIC_VERSION_INFO + */ #define DEFAULT_PCI_ASIC_VERSION_INFO_TABLE \ { \ { PCPS_TYPE_PEX511, PCI_ASIC_MAJOR_PEX511, PCI_ASIC_CURRENT_MINOR_PEX511, PCI_ASIC_REQUIRED_MINOR_PEX511 }, \ @@ -364,16 +490,12 @@ typedef struct { PCPS_TYPE_TCR180PEX, PCI_ASIC_MAJOR_TCR180PEX, PCI_ASIC_CURRENT_MINOR_TCR180PEX, PCI_ASIC_REQUIRED_MINOR_TCR180PEX }, \ { PCPS_TYPE_PZF180PEX, PCI_ASIC_MAJOR_PZF180PEX, PCI_ASIC_CURRENT_MINOR_PZF180PEX, PCI_ASIC_REQUIRED_MINOR_PZF180PEX }, \ { PCPS_TYPE_GLN180PEX, PCI_ASIC_MAJOR_GLN180PEX, PCI_ASIC_CURRENT_MINOR_GLN180PEX, PCI_ASIC_REQUIRED_MINOR_GLN180PEX }, \ + { PCPS_TYPE_GPS180AMC, PCI_ASIC_MAJOR_GPS180PEX, PCI_ASIC_CURRENT_MINOR_GPS180PEX, PCI_ASIC_REQUIRED_MINOR_GPS180PEX }, \ + { PCPS_TYPE_GNS181PEX, PCI_ASIC_MAJOR_GNS181PEX, PCI_ASIC_CURRENT_MINOR_GNS181PEX, PCI_ASIC_REQUIRED_MINOR_GNS181PEX }, \ { 0 } \ } -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - /* ----- function prototypes begin ----- */ /* This section was generated automatically */ @@ -399,4 +521,3 @@ extern "C" { #undef _DO_INIT #endif /* _PCI_ASIC_H */ - diff --git a/c/mbglib/include/pcpsdefs.h b/c/mbglib/include/pcpsdefs.h index 54d22e6..25d16ce 100644 --- a/c/mbglib/include/pcpsdefs.h +++ b/c/mbglib/include/pcpsdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdefs.h 1.55 2014/07/17 10:52:24Z martin REL_M $ + * $Id: pcpsdefs.h 1.65 2019/07/31 15:41:02Z martin REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,7 +10,35 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdefs.h $ - * Revision 1.55 2014/07/17 10:52:24Z martin + * Revision 1.65 2019/07/31 15:41:02Z martin + * Doxygen changes. + * Revision 1.64 2018/06/25 12:34:23 martin + * Fixed spelling inside a comment. + * Revision 1.63 2018/02/28 16:57:38Z martin + * Replace references to frac_sec_from_bin() to bin_frac_32_to_dec_frac(). + * Revision 1.62 2017/07/04 16:24:53 martin + * Moved definitions PCPS_HRT_FRAC_SCALE and PCPS_HRT_FRAC_SCALE_FMT + * back here. + * New types PCPS_SECONDS and PCPS_FRAC_32. + * Fixed typo, wording, and doxygen comments. + * Revision 1.61 2017/04/25 11:38:38 martin + * Renamed GRC181PEX to GNS181PEX. + * Revision 1.60 2017/03/17 12:00:05 martin + * Moved definitions of PCPS_HRT_FRAC_CONVERSION_TYPE, + * PCPS_HRT_BIN_FRAC_SCALE, and PCPS_HRT_FRAC_SCALE_FMT + * to cfg_hlp.h. + * Revision 1.59 2017/01/27 08:11:19 martin + * Fixed macro syntax. + * Revision 1.58 2016/11/08 16:42:52 martin + * New GPS cmd codes PC_GPS_XFEATURE_BUFFER and PC_GPS_TLV_INFO. + * Revision 1.57 2016/11/08 16:40:39 martin + * Doxygen cleanup. + * Revision 1.56 2016/10/26 13:22:41 martin + * Added definitions for GRC181PEX. + * New symbol IRIG_TIME_UNKNOWN_YEAR. + * Removed trailing spaces. + * Updated doxygen comments. + * Revision 1.55 2014/07/17 10:52:24 martin * Increased safety of firmware builds. * Revision 1.54 2014/07/17 09:54:19 martin * New command codes PC_GPS_XMR_HOLDOVER_STATUS @@ -41,7 +69,7 @@ * Support GPIO configuration. * Support PZF180PEX. * Added commands to read CORR_INFO, read/write TR_DISTANCE, - * PCPS_SYNC_PZF status, and associated structures. + * PCPS_SYNC_PZF status, and associated structures. * Added an initializer for a table of GPS command code/names. * Added definitions MBG_PCPS_FMT_STATUS. * Updated some comments. @@ -86,12 +114,12 @@ * Added new REF type PCPS_REF_MSF. * Revision 1.35 2008/01/17 09:18:46Z daniel * Made comments compatible for doxygen parser. - * No sourcecode changes. + * No sourcecode changes. * Revision 1.34 2007/07/17 08:22:47Z martin * Added support for TCR511PEX and GPS170PEX. * Revision 1.33 2007/05/20 21:39:51Z martin * Added support for PEX511. - * Added PCPS_GET_STATUS_PORT cmd code for devices + * Added PCPS_GET_STATUS_PORT cmd code for devices * that do not support a hardware status port. * Revision 1.32 2007/03/29 12:57:32Z martin * Renamed some TZCODE numbers for unique naming conventions. @@ -123,14 +151,14 @@ * Support configuration of on-board frequency synthesizer. * Revision 1.21 2004/11/09 12:55:32Z martin * Redefined interface data types using C99 fixed-size definitions. - * Added workaround macros for some structure sizes because the C166 - * compiler always reports an even structure size even if the structure - * size is in fact odd, which might lead to different sizes in C166 and + * Added workaround macros for some structure sizes because the C166 + * compiler always reports an even structure size even if the structure + * size is in fact odd, which might lead to different sizes in C166 and * other environments. - * Modifications were required in order to be able to configure IRIG + * Modifications were required in order to be able to configure IRIG * settings of cards which provide both IRIG input and output. - * The existing codes have been renamed with .._RX.. and are used to - * configure the IRIG receiver (input). New codes have been defined + * The existing codes have been renamed with .._RX.. and are used to + * configure the IRIG receiver (input). New codes have been defined * used to configure the IRIG transmitter. * Renamed PC_GPS_STAT to PC_GPS_BVAR_STAT. * Use more specific data types than generic types. @@ -148,12 +176,12 @@ * fill level. * Revision 1.16 2003/04/03 10:48:53 martin * Support for PCI510, GPS169PCI, and TCR510PCI. - * New codes PCPS_GET_REF_OFFS, PCPS_SET_REF_OFFS + * New codes PCPS_GET_REF_OFFS, PCPS_SET_REF_OFFS * and related structures. * New codes PCPS_GET_OPT_INFO, PCPS_SET_OPT_SETTINGS * and related structures. * New codes PCPS_GET_IRIG_INFO, PCPS_SET_IRIG_SETTINGS. - * Preliminary PCPS_TZDL structure and cmd codes + * Preliminary PCPS_TZDL structure and cmd codes * to read/write that structure. * Revision 1.15 2002/08/08 13:24:03 MARTIN * Moved definition of ref time sources here. @@ -262,25 +290,30 @@ /** * @brief Enumeration of the ref time signal sources used by Meinberg devices */ -enum +enum PCPS_REF_TYPES { - PCPS_REF_NONE, ///< (unknown or not defined) - PCPS_REF_DCF, ///< see http://www.meinberg.de/english/info/dcf77.htm - PCPS_REF_GPS, ///< see http://www.meinberg.de/english/info/gps.htm - PCPS_REF_IRIG, ///< see http://www.meinberg.de/english/info/irig.htm - PCPS_REF_MSF, ///< MSF Receiver (UK) + PCPS_REF_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 Receiver (US) - PCPS_REF_JJY, ///< JJY Receiver (Japan) + 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" @@ -290,7 +323,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, \ @@ -305,6 +345,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 }, \ @@ -322,6 +367,8 @@ enum /** * @brief Meinberg PCI vendor ID (assigned by the PCI SIG) + * + * @see @ref MEINBERG_PCI_DEVICE_IDS */ #define PCI_VENDOR_MEINBERG 0x1360 @@ -329,7 +376,7 @@ enum /** * @brief PCI device IDs assigned by Meinberg * - * High byte: type of ref time source + * High byte: type of ref time source, see ::PCPS_REF_TYPES * Low Byte: enumeration of device types * * @see ::PCI_VENDOR_MEINBERG @@ -351,6 +398,7 @@ enum #define PCI_DEV_GPS180PEX ( ( PCPS_REF_GPS << 8 ) | 0x06 ) #define PCI_DEV_GLN180PEX ( ( PCPS_REF_GPS << 8 ) | 0x07 ) #define PCI_DEV_GPS180AMC ( ( PCPS_REF_GPS << 8 ) | 0x08 ) +#define PCI_DEV_GNS181PEX ( ( PCPS_REF_GPS << 8 ) | 0x09 ) #define PCI_DEV_TCR510PCI ( ( PCPS_REF_IRIG << 8 ) | 0x01 ) #define PCI_DEV_TCR167PCI ( ( PCPS_REF_IRIG << 8 ) | 0x02 ) @@ -389,20 +437,22 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * @brief Bit masks used with ::PCPS_STATUS_PORT * * The flags ::PCPS_ST_SEC and ::PCPS_ST_MIN are cleared whenever the clock - * is read, so they are not very reliable in multitasking environments. + * is read, so they are not very reliable in multitasking environments + * and thus should be considered as deprecated. * - * The ::PCPS_ST_IRQF flag originates from old ISA cards. + * The ::PCPS_ST_IRQF flag was used with old ISA cards to check + * if the device has generated an IRQ. * Some PCI cards also support this, but in case of PCI cards the * associated flag of the PCI interface chip should be checked to see * if a particular card has generated an IRQ on the PC bus. * - * The macro _pcps_ddev_has_gen_irq() cares about this and should be used + * The macro ::_pcps_ddev_has_gen_irq cares about this and should be used * to determine in a portable way whether a card has generated an IRQ. * * @anchor PCPS_STATUS_PORT_BIT_MASKS @{ */ #define PCPS_ST_BUSY 0x01 ///< the clock is busy filling the output FIFO -#define PCPS_ST_IRQF 0x02 ///< the clock has generated an IRQ on the PC bus (ISA only) +#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 @@ -425,9 +475,11 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS /** * @brief Command codes used to communicate with bus level devices * - * The commands described below are used to access computer peripherals + * 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 @@ -438,339 +490,312 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS * the command code is passed. Every parameter byte has to be supplied * to the board exactly like a command byte. * - * Refer to function pcps_write_data() and the macro _pcps_write_var() + * Refer to function ::pcps_write and the macro ::_pcps_write_var * for details. * - * - #PCPS_GIVE_TIME<br> - * Return a PCPS_TIME structure with current date, - * time and status. Supported by all clocks. - * - * - #PCPS_GIVE_TIME_NOCLEAR<br> - * Same as #PCPS_GIVE_TIME but the bits #PCPS_ST_SEC - * and #PCPS_ST_MIN (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> + * - ::PCPS_GIVE_TIME<br> + * Return a ::PCPS_TIME structure with current date, + * time and status. Supported by all clocks. + * + * - ::PCPS_GIVE_TIME_NOCLEAR<br> + * Same as ::PCPS_GIVE_TIME but the bits ::PCPS_ST_SEC + * and ::PCPS_ST_MIN of the status port are not cleared. + * Supported by all clocks except PC31/PS31 with + * firmware version older than v3.0. + * This is mainly used by the DOS TSR and should + * not be used in other environments. + * + * - ::PCPS_GIVE_SYNC_TIME<br> + * Return a ::PCPS_TIME structure with date and time + * of last synchronization of the clock or + * the last time set via the interface. + * ::_pcps_has_sync_time checks whether supported. + * + * - ::PCPS_GIVE_HR_TIME<br> + * Return a ::PCPS_HR_TIME structure with current + * date, time and status. This command should be + * used to read the clock with higher resolution. + * ::_pcps_has_hr_time checks whether supported. + * + * - ::PCPS_GIVE_IRIG_TIME<br> + * Return a ::PCPS_IRIG_TIME structure with day-of-year, + * time and status as decoded from the IRIG signal. + * ::_pcps_has_irig_time checks whether supported. + * + * - ::PCPS_SET_TIME<br> + * Set the board date, time and status. This command + * expects sizeof( ::PCPS_STIME ) parameter bytes. + * ::_pcps_can_set_time checks whether supported. + * + * - ::PCPS_SET_EVENT_TIME<br> + * Send a high resolution time stamp to the clock to + * configure a %UTC time when the clock shall generate + * some event. This command expects a ::PCPS_TIME_STAMP + * parameter. + * ::_pcps_has_event_time checks whether supported. + * (requires custom GPS CERN firmware) + * + * - ::PCPS_IRQ_NONE<br> + * Disable the card's hardware IRQ<br> + * - ::PCPS_IRQ_1_SEC<br> + * Enable hardware IRQs once per second<br> + * - ::PCPS_IRQ_1_MIN<br> + * Enable hardware IRQs once per minute (deprecated)<br> + * - ::PCPS_IRQ_10_MIN<br> + * Enable hardware IRQs once per 10 minutes (deprecated)<br> + * - ::PCPS_IRQ_30_MIN<br> + * Enable hardware IRQs once per 30 minutes (deprecated)<br> + * + * - ::PCPS_GET_SERIAL<br> + * ::PCPS_SET_SERIAL<br> + * Deprecated. Read or write the configuration of a card's + * serial port COM0 in ::PCPS_SERIAL format. + * ::_pcps_has_serial checks whether supported. + * Newer cards should be configured using the structures ::RECEIVER_INFO, + * ::PORT_INFO, and STR_TYPE_INFO. + * ::_pcps_has_receiver_info checks whether these are supported. + * + * - ::PCPS_GET_TZCODE<br> + * ::PCPS_SET_TZCODE<br> + * These commands read or set a DCF77 clock's + * time zone code and should be used preferably + * with older DCF77 receivers which have limited + * support of different time zones. + * ::_pcps_has_tzcode checks whether supported. + * Most newer devices support the ::TZDL structure which can be + * read or written using ::PC_GPS_TZDL. + * + * - ::PCPS_GET_PCPS_TZDL<br> + * ::PCPS_SET_PCPS_TZDL<br> + * Read or write time zone / daylight saving information + * in ::PCPS_TZDL format. + * ::_pcps_has_pcps_tzdl checks whether supported. + * + * - ::PCPS_GET_REF_OFFS<br> + * ::PCPS_SET_REF_OFFS<br> + * These commands can be used to configure the + * reference time offset from %UTC for clocks + * which can't determine the offset automatically, + * e.g. from an IRIG input signal. + * ::_pcps_has_ref_offs checks whether supported. + * + * - ::PCPS_GET_OPT_INFO<br> + * ::PCPS_SET_OPT_SETTINGS<br> + * These commands can be used to configure some + * optional settings, controlled by flags. + * When reading, the clock returns a ::MBG_OPT_INFO + * structure which contains the supported values, + * plus the current settings. + * When writing, clocks accepts a ::MBG_OPT_SETTINGS + * structure only which contain the desired settings + * of the supported flags only. + * ::_pcps_has_opt_flags checks whether supported. + * + * - ::PCPS_GET_IRIG_RX_INFO<br> + * ::PCPS_SET_IRIG_RX_SETTINGS<br> + * ::PCPS_GET_IRIG_TX_INFO<br> + * ::PCPS_SET_IRIG_TX_SETTINGS<br> + * These commands can be used to configure IRIG + * inputs and outputs.<br> + * When reading, the clock returns an ::IRIG_INFO + * structure which contains the supported values, + * plus the current settings.<br> + * When writing, clocks accepts an ::IRIG_SETTINGS + * structure only which contain the desired settings + * only. ::_pcps_is_irig_rx and ::_pcps_has_irig_tx + * check whether supported. + * + * - ::PCPS_GET_IRIG_CTRL_BITS<br> + * This command can be used to retrieve the control function + * bits of the latest IRIG input frame. Those bits may carry + * some well-known information as in the IEEE 1344 code, but + * may also contain some customized information, depending on + * the IRIG frame type and the configuration of the IRIG generator. + * So these bits are returned as-is and must be interpreted + * by the application. + * ::_pcps_has_irig_ctrl_bits checks whether supported. + * + * - ::PCPS_GET_SYNTH<br> + * ::PCPS_SET_SYNTH<br> + * ::PCPS_GET_SYNTH_STATE<br> * These commands can be used to configure an on-board * frequency synthesizer and query the synthesizer * status. The commands are only supported if the board - * supports the RECEIVER_INFO structure and the flag - * #GPS_HAS_SYNTH is set in the RECEIVER_INFO::features. - * _pcps_has_synth() checks whether supported. - * The structures SYNTH and SYNTH_STATE used with these + * 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. + * - ::PCPS_GIVE_FW_ID_1<br> + * ::PCPS_GIVE_FW_ID_2<br> + * Returns the first/second block of ::PCPS_FIFO_SIZE + * characters of the firmware ID string. These + * commands can be used to check if the board + * responds properly. This is done by the clock + * detection functions. + * + * - ::PCPS_GIVE_SERNUM<br> + * Returns ::PCPS_FIFO_SIZE characters of the + * clock's serial number. + * ::_pcps_has_sernum checks whether supported. + * + * - ::PCPS_GENERIC_IO<br> + * Generic I/O read and write. Can be used to query + * specific data, e.g. a selected element of an array. + * ::_pcps_has_generic_io checks whether supported. + * + * - ::PCPS_GET_DEBUG_STATUS<br> + * This command reads an ::MBG_DEBUG_STATUS structure + * which represents the internal status of the + * IRIG decoder and some additional debug info. + * ::_pcps_has_debug_status checks whether supported. + * + * - ::PCPS_READ_GPS_DATA<br> + * ::PCPS_WRITE_GPS_DATA<br> + * These commands are used by the functions + * ::pcps_read_gps and ::pcps_write_gps + * to read or write large data structures to + * Meinberg GPS plug-in clocks. + * ::_pcps_is_gps checks whether supported. + * + * - ::PCPS_CLR_UCAP_BUFF<br> + * Clear a clock's time capture buffer. + * ::_pcps_can_clr_ucap_buff checks whether + * supported. + * + * - ::PCPS_GIVE_UCAP_ENTRIES<br> + * Read a ::PCPS_UCAP_ENTRIES structure which + * reports the max number of entries and the + * currently used number of entries in the + * user capture buffer. + * ::_pcps_has_ucap checks whether supported. + * + * - ::PCPS_GIVE_UCAP_EVENT<br> + * Read capture events using a PCPS_HR_TIME + * structure. This is faster than reading using the + * GPS command ::PC_GPS_UCAP. If no capture event is + * available then the returned structure is all 0. + * ::_pcps_has_ucap checks whether supported. + * + * - ::PCPS_GET_CORR_INFO<br> + * Read PZF correlation info using a ::CORR_INFO + * structure. + * ::_pcps_has_pzf checks whether supported. + * + * - ::PCPS_GET_TR_DISTANCE<br> + * ::PCPS_SET_TR_DISTANCE<br> + * Read or write distance from the RF transmitter. + * This is used to compensate the RF propagation delay + * for PZF receivers. + * ::_pcps_has_tr_distance checks whether supported. + * + * - ::PCPS_CLR_EVT_LOG<br> + * Clear on-board event log. + * ::_pcps_has_evt_log checks whether supported. + * + * - ::PCPS_NUM_EVT_LOG_ENTRIES<br> + * Read max. number of num event log entries which can + * be saved on the board, and how many entries have currently + * been saved. + * ::_pcps_has_evt_log checks whether supported. + * + * - ::PCPS_FIRST_EVT_LOG_ENTRY<br> + * ::PCPS_NEXT_EVT_LOG_ENTRY<br> + * Read first (oldest) or next event log entry. + * ::_pcps_has_evt_log checks whether supported. + * + * - ::PCPS_FORCE_RESET<br> + * Resets the card's hardware. This may lock up the computer + * and thus should only be used by very specific applications. * * @anchor PCPS_CMD_CODES @{ */ -#define PCPS_GIVE_TIME 0x00 ///< (r-) read current time in ::PCPS_TIME format -#define PCPS_GIVE_TIME_NOCLEAR 0x01 ///< (r-) read current time in ::PCPS_TIME format, don't clear sec and min flags -#define PCPS_GIVE_SYNC_TIME 0x02 ///< (r-) read last sync time as ::PCPS_TIME, only if ::_pcps_has_sync_time() -#define PCPS_GIVE_HR_TIME 0x03 ///< (r-) read high res. time as ::PCPS_HR_TIME, only if ::_pcps_has_hr_time() -#define PCPS_GIVE_IRIG_TIME 0x04 ///< (r-) read raw IRIG time as ::PCPS_IRIG_TIME, only if ::_pcps_has_irig_time() +#define PCPS_GIVE_TIME 0x00 ///< (r-) Read current time in ::PCPS_TIME format +#define PCPS_GIVE_TIME_NOCLEAR 0x01 ///< (r-) Read current time in ::PCPS_TIME format, don't clear sec and min flags (deprecated) +#define PCPS_GIVE_SYNC_TIME 0x02 ///< (r-) Read last sync time as ::PCPS_TIME, only if ::_pcps_has_sync_time +#define PCPS_GIVE_HR_TIME 0x03 ///< (r-) Read high res. time as ::PCPS_HR_TIME, only if ::_pcps_has_hr_time +#define PCPS_GIVE_IRIG_TIME 0x04 ///< (r-) Read raw IRIG time as ::PCPS_IRIG_TIME, only if ::_pcps_has_irig_time -#define PCPS_SET_TIME 0x10 ///< (-w) set on-board time, see ::PCPS_STIME -/* on error, return PCPS_ERR_STIME */ +#define PCPS_SET_TIME 0x10 ///< (-w) Set on-board time, see ::PCPS_STIME. Returns ::MBG_ERR_STIME on error. -#define PCPS_SET_EVENT_TIME 0x14 ///< (-w) write event time as ::PCPS_TIME_STAMP, only if ::_pcps_has_event_time() +#define PCPS_SET_EVENT_TIME 0x14 ///< (-w) Write event time as ::PCPS_TIME_STAMP, only if ::_pcps_has_event_time -#define PCPS_IRQ_NONE 0x20 ///< (-w) disable IRQs -#define PCPS_IRQ_1_SEC 0x21 ///< (-w) enable IRQ per 1 second -#define PCPS_IRQ_1_MIN 0x22 ///< (-w) enable IRQ per 1 minute (deprecated) -#define PCPS_IRQ_10_MIN 0x24 ///< (-w) enable IRQ per 10 minutes (deprecated) -#define PCPS_IRQ_30_MIN 0x28 ///< (-w) enable IRQ per 10 minutes (deprecated) +#define PCPS_IRQ_NONE 0x20 ///< (-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 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 */ +#define PCPS_GET_SERIAL 0x30 ///< (r-) Read serial settings as ::PCPS_SERIAL, deprecated by ::PC_GPS_ALL_PORT_INFO +#define PCPS_SET_SERIAL 0x31 ///< (-w) Write serial settings as ::PCPS_SERIAL, deprecated by ::PC_GPS_PORT_SETTINGS_IDX, returns ::MBG_ERR_CFG on error -#define PCPS_GET_TZCODE 0x32 ///< (r-) read ::PCPS_TZCODE, only if ::_pcps_has_tzcode() -#define PCPS_SET_TZCODE 0x33 ///< (-w) write ::PCPS_TZCODE, only if ::_pcps_has_tzcode() -/* on error, return PCPS_ERR_CFG */ +#define PCPS_GET_TZCODE 0x32 ///< (r-) Read ::PCPS_TZCODE, only if ::_pcps_has_tzcode +#define PCPS_SET_TZCODE 0x33 ///< (-w) Write ::PCPS_TZCODE, only if ::_pcps_has_tzcode, returns ::MBG_ERR_CFG on error -#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 */ +#define PCPS_GET_PCPS_TZDL 0x34 ///< (r-) Read ::PCPS_TZDL, only if ::_pcps_has_pcps_tzdl +#define PCPS_SET_PCPS_TZDL 0x35 ///< (-w) Write ::PCPS_TZDL, only if ::_pcps_has_pcps_tzdl, returns ::MBG_ERR_CFG on error -#define PCPS_GET_REF_OFFS 0x36 ///< (r-) read ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs() -#define PCPS_SET_REF_OFFS 0x37 ///< (-w) write ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs() -/* on error, return PCPS_ERR_CFG */ +#define PCPS_GET_REF_OFFS 0x36 ///< (r-) Read ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs +#define PCPS_SET_REF_OFFS 0x37 ///< (-w) Write ::MBG_REF_OFFS, only if ::_pcps_has_ref_offs, returns ::MBG_ERR_CFG on error -#define PCPS_GET_OPT_INFO 0x38 ///< (r-) read ::MBG_OPT_INFO, only if ::_pcps_has_opt_flags() -#define PCPS_SET_OPT_SETTINGS 0x39 ///< (-w) write ::MBG_OPT_SETTINGS, only if ::_pcps_has_opt_flags() -/* on error, return PCPS_ERR_CFG */ +#define PCPS_GET_OPT_INFO 0x38 ///< (r-) Read ::MBG_OPT_INFO, only if ::_pcps_has_opt_flags +#define PCPS_SET_OPT_SETTINGS 0x39 ///< (-w) Write ::MBG_OPT_SETTINGS, only if ::_pcps_has_opt_flags, returns ::MBG_ERR_CFG on error -#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_RX_INFO 0x3A ///< (r-) Read ::IRIG_INFO, only if ::_pcps_is_irig_rx +#define PCPS_SET_IRIG_RX_SETTINGS 0x3B ///< (-w) Write ::IRIG_SETTINGS, only if ::_pcps_is_irig_rx, returns ::MBG_ERR_CFG on error -#define PCPS_GET_IRIG_TX_INFO 0x3C ///< (r-) read ::IRIG_INFO, only if ::_pcps_has_irig_tx() -#define PCPS_SET_IRIG_TX_SETTINGS 0x3D ///< (-w) write ::IRIG_SETTINGS, only if ::_pcps_has_irig_tx() -/* 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, returns ::MBG_ERR_CFG on error -#define PCPS_GET_SYNTH 0x3E ///< (r-) read ::SYNTH, only if ::_pcps_has_synth() -#define PCPS_SET_SYNTH 0x3F ///< (-w) write ::SYNTH, only if ::_pcps_has_synth() -/* on error, return PCPS_ERR_CFG */ +#define PCPS_GET_SYNTH 0x3E ///< (r-) Read ::SYNTH, only if ::_pcps_has_synth +#define PCPS_SET_SYNTH 0x3F ///< (-w) Write ::SYNTH, only if ::_pcps_has_synth, returns ::MBG_ERR_CFG on error -#define PCPS_GIVE_FW_ID_1 0x40 ///< (r-) 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_GIVE_FW_ID_1 0x40 ///< (r-) Read first ::PCPS_FIFO_SIZE chars of firmware ID +#define PCPS_GIVE_FW_ID_2 0x41 ///< (r-) Read last ::PCPS_FIFO_SIZE chars of firmware ID +#define PCPS_GIVE_SERNUM 0x42 ///< (r-) Read serial number as ::PCPS_SN_STR, only if ::_pcps_has_sernum +#define PCPS_GENERIC_IO 0x43 ///< (rw) See ::pcps_generic_io or ::_mbgdevio_gen_io +#define PCPS_GET_SYNTH_STATE 0x44 ///< (r-) Read ::SYNTH_STATE, only if ::_pcps_has_synth +#define PCPS_GET_IRIG_CTRL_BITS 0x45 ///< (r-) Read ::MBG_IRIG_CTRL_BITS, only if ::_pcps_has_irig_ctrl_bits +#define PCPS_GET_RAW_IRIG_DATA 0x46 ///< (r-) Read ::MBG_RAW_IRIG_DATA, only if ::_pcps_has_raw_irig_data -#define PCPS_GET_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_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 -// Command codes 0x4D, 0x4E, and 0x4F are reserved. +/// @note Command codes 0x4D, 0x4E, and 0x4F are reserved. -#define PCPS_READ_GPS_DATA 0x50 ///< (r-) read large data structure, see ::PC_GPS_CMD_CODES -#define PCPS_WRITE_GPS_DATA 0x51 ///< (-w) write large data structure, see ::PC_GPS_CMD_CODES +#define PCPS_READ_GPS_DATA 0x50 ///< (r-) Read large data structure, see ::PC_GPS_CMD_CODES +#define PCPS_WRITE_GPS_DATA 0x51 ///< (-w) Write large data structure, see ::PC_GPS_CMD_CODES -#define PCPS_CLR_UCAP_BUFF 0x60 ///< (-w) no param., clear on-board capture FIFO, only if ::_pcps_has_ucap() -#define PCPS_GIVE_UCAP_ENTRIES 0x61 ///< (r-) read ::PCPS_UCAP_ENTRIES, only if ::_pcps_has_ucap() -#define PCPS_GIVE_UCAP_EVENT 0x62 ///< (r-) return oldes event as ::PCPS_HR_TIME, only if ::_pcps_has_ucap() +#define PCPS_CLR_UCAP_BUFF 0x60 ///< (-w) No param., clear on-board capture FIFO, only if ::_pcps_has_ucap +#define PCPS_GIVE_UCAP_ENTRIES 0x61 ///< (r-) Read ::PCPS_UCAP_ENTRIES, only if ::_pcps_has_ucap +#define PCPS_GIVE_UCAP_EVENT 0x62 ///< (r-) Return oldest event as ::PCPS_HR_TIME, only if ::_pcps_has_ucap -#define PCPS_GET_CORR_INFO 0x63 ///< (r-) read ::CORR_INFO structure, only if _pcps_has_pzf() -#define PCPS_GET_TR_DISTANCE 0x64 ///< (r-) read ::TR_DISTANCE, only if _pcps_has_tr_distance() -#define PCPS_SET_TR_DISTANCE 0x65 ///< (-w) write ::TR_DISTANCE, only if _pcps_has_tr_distance() +#define PCPS_GET_CORR_INFO 0x63 ///< (r-) Read ::CORR_INFO structure, only if ::_pcps_has_pzf +#define PCPS_GET_TR_DISTANCE 0x64 ///< (r-) Read ::TR_DISTANCE, only if ::_pcps_has_tr_distance +#define PCPS_SET_TR_DISTANCE 0x65 ///< (-w) Write ::TR_DISTANCE, only if ::_pcps_has_tr_distance -#define PCPS_CLR_EVT_LOG 0x66 ///< (-w) write clear on-board event log, only if _pcps_has_evt_log() -#define PCPS_NUM_EVT_LOG_ENTRIES 0x67 ///< (r-) read ::MBG_NUM_EVT_LOG_ENTRIES, only if _pcps_has_evt_log() -#define PCPS_FIRST_EVT_LOG_ENTRY 0x68 ///< (r-) read first (oldest) ::MBG_EVT_LOG_ENTRY, only if _pcps_has_evt_log() -#define PCPS_NEXT_EVT_LOG_ENTRY 0x69 ///< (r-) read next ::MBG_EVT_LOG_ENTRY, only if _pcps_has_evt_log() +#define PCPS_CLR_EVT_LOG 0x66 ///< (-w) Write clear on-board event log, only if ::_pcps_has_evt_log +#define PCPS_NUM_EVT_LOG_ENTRIES 0x67 ///< (r-) Read ::MBG_NUM_EVT_LOG_ENTRIES, only if ::_pcps_has_evt_log +#define PCPS_FIRST_EVT_LOG_ENTRY 0x68 ///< (r-) Read first (oldest) ::MBG_EVT_LOG_ENTRY, only if ::_pcps_has_evt_log +#define PCPS_NEXT_EVT_LOG_ENTRY 0x69 ///< (r-) Read next ::MBG_EVT_LOG_ENTRY, only if ::_pcps_has_evt_log -#define PCPS_FORCE_RESET 0x80 ///< (-w) no param., reset the device (this can lockup the computer!!) +#define PCPS_FORCE_RESET 0x80 ///< (-w) No param., reset the device (deprecated, this can lock up the computer!!) -// Command codes 0xF0 through 0xFF are reserved. +/// @note Command codes 0xF0 through 0xFF are reserved. /** @} anchor PCPS_CMD_CODES */ -#if _IS_MBG_FIRMWARE //##++ +#if _IS_MBG_FIRMWARE /** * @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 + * from existing source code. The explicit command * codes @ref PCPS_CMD_CODES should be used instead. * * @anchor PCPS_CMD_GROUP_CODES @{ */ @@ -797,63 +822,65 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS /** * @brief An initializer for a table of code/name entries of non-GPS commands. * - * This can e.g. be assigned to an array of ::MBG_CODE_NAME_TABLE_ENTRY elements + * 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 MBG_CMD_TABLE \ -{ \ - _mbg_cn_table_entry( PCPS_GIVE_TIME ), /* 00 */ \ - _mbg_cn_table_entry( PCPS_GIVE_TIME_NOCLEAR ), /* 01 */ \ - _mbg_cn_table_entry( PCPS_GIVE_SYNC_TIME ), /* 02 */ \ - _mbg_cn_table_entry( PCPS_GIVE_HR_TIME ), /* 03 */ \ - _mbg_cn_table_entry( PCPS_GIVE_IRIG_TIME ), /* 04 */ \ - _mbg_cn_table_entry( PCPS_SET_TIME ), /* 10 */ \ - _mbg_cn_table_entry( PCPS_SET_EVENT_TIME ), /* 14 */ \ - _mbg_cn_table_entry( PCPS_IRQ_NONE ), /* 20 */ \ - _mbg_cn_table_entry( PCPS_IRQ_1_SEC ), /* 21 */ \ - _mbg_cn_table_entry( PCPS_IRQ_1_MIN ), /* 22 */ \ - _mbg_cn_table_entry( PCPS_IRQ_10_MIN ), /* 24 */ \ - _mbg_cn_table_entry( PCPS_IRQ_30_MIN ), /* 28 */ \ - _mbg_cn_table_entry( PCPS_GET_SERIAL ), /* 30 */ \ - _mbg_cn_table_entry( PCPS_SET_SERIAL ), /* 31 */ \ - _mbg_cn_table_entry( PCPS_GET_TZCODE ), /* 32 */ \ - _mbg_cn_table_entry( PCPS_SET_TZCODE ), /* 33 */ \ - _mbg_cn_table_entry( PCPS_GET_PCPS_TZDL ), /* 34 */ \ - _mbg_cn_table_entry( PCPS_SET_PCPS_TZDL ), /* 35 */ \ - _mbg_cn_table_entry( PCPS_GET_REF_OFFS ), /* 36 */ \ - _mbg_cn_table_entry( PCPS_SET_REF_OFFS ), /* 37 */ \ - _mbg_cn_table_entry( PCPS_GET_OPT_INFO ), /* 38 */ \ - _mbg_cn_table_entry( PCPS_SET_OPT_SETTINGS ), /* 39 */ \ - _mbg_cn_table_entry( PCPS_GET_IRIG_RX_INFO ), /* 3A */ \ - _mbg_cn_table_entry( PCPS_SET_IRIG_RX_SETTINGS ), /* 3B */ \ - _mbg_cn_table_entry( PCPS_GET_IRIG_TX_INFO ), /* 3C */ \ - _mbg_cn_table_entry( PCPS_SET_IRIG_TX_SETTINGS ), /* 3D */ \ - _mbg_cn_table_entry( PCPS_GET_SYNTH ), /* 3E */ \ - _mbg_cn_table_entry( PCPS_SET_SYNTH ), /* 3F */ \ - _mbg_cn_table_entry( PCPS_GIVE_FW_ID_1 ), /* 40 */ \ - _mbg_cn_table_entry( PCPS_GIVE_FW_ID_2 ), /* 41 */ \ - _mbg_cn_table_entry( PCPS_GIVE_SERNUM ), /* 42 */ \ - _mbg_cn_table_entry( PCPS_GENERIC_IO ), /* 43 */ \ - _mbg_cn_table_entry( PCPS_GET_SYNTH_STATE ), /* 44 */ \ - _mbg_cn_table_entry( PCPS_GET_IRIG_CTRL_BITS ), /* 45 */ \ - _mbg_cn_table_entry( PCPS_GET_RAW_IRIG_DATA ), /* 46 */ \ - _mbg_cn_table_entry( PCPS_GET_STATUS_PORT ), /* 4B */ \ - _mbg_cn_table_entry( PCPS_GET_DEBUG_STATUS ), /* 4C */ \ - _mbg_cn_table_entry( PCPS_READ_GPS_DATA ), /* 50 */ \ - _mbg_cn_table_entry( PCPS_WRITE_GPS_DATA ), /* 51 */ \ - _mbg_cn_table_entry( PCPS_CLR_UCAP_BUFF ), /* 60 */ \ - _mbg_cn_table_entry( PCPS_GIVE_UCAP_ENTRIES ), /* 61 */ \ - _mbg_cn_table_entry( PCPS_GIVE_UCAP_EVENT ), /* 62 */ \ - _mbg_cn_table_entry( PCPS_GET_CORR_INFO ), /* 63 */ \ - _mbg_cn_table_entry( PCPS_GET_TR_DISTANCE ), /* 64 */ \ - _mbg_cn_table_entry( PCPS_SET_TR_DISTANCE ), /* 65 */ \ - _mbg_cn_table_entry( PCPS_CLR_EVT_LOG ), /* 66 */ \ - _mbg_cn_table_entry( PCPS_NUM_EVT_LOG_ENTRIES ), /* 67 */ \ - _mbg_cn_table_entry( PCPS_FIRST_EVT_LOG_ENTRY ), /* 68 */ \ - _mbg_cn_table_entry( PCPS_NEXT_EVT_LOG_ENTRY ), /* 69 */ \ - _mbg_cn_table_entry( PCPS_FORCE_RESET ), /* 80 */ \ - MBG_CMD_TABLE_EXT, \ - _mbg_cn_table_end() \ +#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() \ } @@ -861,13 +888,14 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS /** * @brief Bus level command return codes * - * Codes returned when commands with parameters have been passed to a device + * @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 -#define PCPS_ERR_STIME -1 ///< invalid date/time/status passed -#define PCPS_ERR_CFG -2 ///< invalid parms for a cmd writing config parameters +#define PCPS_SUCCESS 0 ///< OK, no error (see ::MBG_SUCCESS) +#define PCPS_ERR_STIME -1 ///< invalid date/time/status passed (see ::MBG_ERR_STIME) +#define PCPS_ERR_CFG -2 ///< invalid parms for a cmd writing config parameters (see ::MBG_ERR_CFG) /** @} anchor PCPS_LEVEL_CMD_RETURN_CODES */ @@ -878,65 +906,107 @@ typedef uint8_t PCPS_STATUS_PORT; ///< see @ref PCPS_STATUS_PORT_BIT_MASKS #endif -/** - * @brief The size of a bus level device's command/data 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]; +/** @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]; +/** @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]; /** - * @brief A high resolution time stamp + * @brief Seconds since epoch 1970-01-01, usually %UTC scale + * + * Used with ::PCPS_TIME_STAMP. + * + * @see ::PCPS_FRAC_32 + * @see ::PCPS_TIME_STAMP */ -typedef struct -{ - uint32_t sec; ///< seconds since 1970, usually %UTC - uint32_t frac; ///< fractions of second ( 0xFFFFFFFF == 0.9999.. sec) -} PCPS_TIME_STAMP; - -#define _mbg_swab_pcps_time_stamp( _p ) \ -{ \ - _mbg_swab32( &(_p)->sec ); \ - _mbg_swab32( &(_p)->frac ); \ -} +typedef uint32_t PCPS_SECONDS; +#define _mbg_swab_pcps_seconds( _p ) \ +do \ +{ \ + _mbg_swab32( _p ); \ +} while ( 0 ) -// Depending on the target environment define a data type -// which can be used to convert binary fractions without -// range overflow. -#if defined( MBG_TGT_MISSING_64_BIT_TYPES ) - #define PCPS_HRT_FRAC_CONVERSION_TYPE double -#else - #define PCPS_HRT_FRAC_CONVERSION_TYPE int64_t -#endif /** - * @brief Constant used to convert ::PCPS_TIME_STAMP::frac values + * @brief 32 bit binary fraction of a second * - * Max value of ::PCPS_TIME_STAMP::frac + 1, used for scaling + * Used with ::PCPS_TIME_STAMP, e.g. + * 0x80000000 == 0.5 s, 0xFFFFFFFF == 0.9999999.. s, etc. + * Use ::bin_frac_32_to_dec_frac for conversion. + * + * @see ::bin_frac_32_to_dec_frac + * @see ::PCPS_SECONDS + * @see ::PCPS_TIME_STAMP + * @see ::PCPS_HRT_FRAC_SCALE + * @see ::PCPS_HRT_FRAC_SCALE_FMT + */ +typedef uint32_t PCPS_FRAC_32; + +#define _mbg_swab_pcps_frac_32( _p ) \ +do \ +{ \ + _mbg_swab32( _p ); \ +} while ( 0 ) + + + +/** + * @brief A high resolution time stamp */ -#define PCPS_HRT_BIN_FRAC_SCALE ( (PCPS_HRT_FRAC_CONVERSION_TYPE) 4294967296.0 ) // == 0x100000000 +typedef struct +{ + PCPS_SECONDS sec; ///< seconds since 1970, usually %UTC scale + PCPS_FRAC_32 frac; ///< binary fractions of second, see ::PCPS_FRAC_32 + +} PCPS_TIME_STAMP; + +#define _mbg_swab_pcps_time_stamp( _p ) \ +do \ +{ \ + _mbg_swab_pcps_seconds( &(_p)->sec ); \ + _mbg_swab_pcps_frac_32( &(_p)->frac ); \ +} while ( 0 ) + -// The scale and format to be used to print the fractions -// of a second as returned in the PCPS_TIME_STAMP structure. -// The function frac_sec_from_bin() can be used for -// the conversion. #ifndef PCPS_HRT_FRAC_SCALE + /** + * @brief Scale to be used to print ::PCPS_TIME_STAMP::frac values + * + * The function ::bin_frac_32_to_dec_frac can be used for the conversion. + * + * @see ::PCPS_HRT_FRAC_SCALE_FMT + */ #define PCPS_HRT_FRAC_SCALE 10000000UL #endif #ifndef PCPS_HRT_FRAC_SCALE_FMT + /** + * @brief Format specifier used to print ::PCPS_TIME_STAMP::frac values + * + * Used to print values scaled with ::bin_frac_32_to_dec_frac called + * with ::PCPS_HRT_FRAC_SCALE. + * + * @see ::PCPS_HRT_FRAC_SCALE + */ #define PCPS_HRT_FRAC_SCALE_FMT "%07lu" #endif @@ -948,6 +1018,7 @@ typedef struct * 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; @@ -963,10 +1034,11 @@ typedef struct } PCPS_TIME_STATUS_X_MASKS; #define _mbg_swab_pcps_time_status_x_masks( _p ) \ +do \ { \ _mbg_swab_pcps_time_status_x( &(_p)->set_mask ); \ _mbg_swab_pcps_time_status_x( &(_p)->clr_mask ); \ -} +} while ( 0 ) @@ -997,33 +1069,37 @@ typedef uint8_t PCPS_SIG_VAL; /** - * The structure has been introduced to be able to read the - * current time with higher resolution of fractions of seconds and - * more detailed information on the time zone and status. - * The structure is returned if the new command #PCPS_GIVE_HR_TIME - * is written to the board. - * _pcps_has_hr_time() checks whether supported. - * - * Newer GPS boards also accept the #PCPS_GIVE_UCAP_EVENT command - * to return user capture event times using this format. In this - * case, the "signal" field contains the number of the capture - * input line, e.g. 0 or 1. - * _pcps_has_ucap() checks whether supported. + * @brief High resolution time including status and local time offset + * + * Used to read time with high resolution of fractions of seconds and + * more detailed information on the local time offset and status. + * Should be prefered over ::PCPS_TIME. + * + * ::_pcps_has_hr_time checks whether the command ::PCPS_GIVE_TIME is + * supported to read a device's current time using this format. + * + * Newer devices providing time capture input may also accept the + * ::PCPS_GIVE_UCAP_EVENT command to read user capture event times + * using this format. In this case, the "signal" field contains + * the number of the capture input line, e.g. 0 or 1. + * ::_pcps_has_ucap checks whether this is supported. */ typedef struct { PCPS_TIME_STAMP tstamp; ///< High resolution time stamp (%UTC) int32_t utc_offs; ///< %UTC offs [sec] (loc_time = tstamp + utc_offs) PCPS_TIME_STATUS_X status; ///< status bits, see @ref PCPS_TIME_STATUS_FLAGS - PCPS_SIG_VAL signal; ///< signal strength, different meanings, see notes for @ref PCPS_SIG_VAL_DEFS + PCPS_SIG_VAL signal; ///< signal strength, see @ref PCPS_SIG_VAL_DEFS, or capture input channel number + } PCPS_HR_TIME; #define _mbg_swab_pcps_hr_time( _p ) \ +do \ { \ _mbg_swab_pcps_time_stamp( &(_p)->tstamp ); \ _mbg_swab32( &(_p)->utc_offs ); \ _mbg_swab_pcps_time_status_x( &(_p)->status ); \ -} +} while ( 0 ) /** @@ -1042,8 +1118,8 @@ typedef uint8_t PCPS_TIME_STATUS; /** * @brief Local calendar date and time, plus sync status * - * This legacy structure is supported by all devices but has - * a time resultion of 10 ms only. For more accurate time stamps + * 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. * @@ -1053,7 +1129,7 @@ typedef uint8_t PCPS_TIME_STATUS; */ typedef struct { - uint8_t sec100; ///< hundredths of seconds, 0..99 + 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 @@ -1063,9 +1139,10 @@ typedef struct uint8_t month; ///< month, 1..12 uint8_t year; ///< year of the century, 0..99 - PCPS_TIME_STATUS status; ///< status bits, see below - PCPS_SIG_VAL signal; ///< signal strength, different meanings, see notes for @ref PCPS_SIG_VAL_DEFS - int8_t offs_utc; ///< [hours], 0 if !_pcps_has_utc_offs() + 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; @@ -1073,11 +1150,14 @@ typedef struct /** * @brief Date time and status used with the ::PCPS_SET_TIME command * - * @see ::PCPS_STIME + * 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 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 @@ -1092,9 +1172,9 @@ typedef struct } PCPS_STIME; #ifdef _C166 - // This is a workaround to specify some structure sizes. The C166 compiler - // always reports an even structure size although the structure size may - // be odd due to the number of bytes. This might lead to errors between + // This is a workaround to specify some structure sizes. The C166 compiler + // always reports an even structure size although the structure size may + // be odd due to the number of bytes. This might lead to errors between // the C166 and other build environments. #define sizeof_PCPS_TIME ( sizeof( PCPS_TIME ) - 1 ) #define sizeof_PCPS_STIME ( sizeof( PCPS_STIME ) - 1 ) @@ -1107,41 +1187,57 @@ typedef union { PCPS_TIME t; PCPS_STIME stime; + } PCPS_TIME_UNION; /** - The structure below can be used to read the raw IRIG time - from an IRIG receiver card, if the card supports this. - See the #PCPS_GIVE_IRIG_TIME command. - - The granularity of the value in the .frac field depends on - the update interval of the structure as implementation - in the firmware. I.e. if the raw IRIG time is updated - only once per second, the .frac value can always be 0. -*/ -typedef struct PCPS_IRIG_TIME_s + * @brief Raw IRIG time + * + * Used to read the raw IRIG time from an IRIG receiver card, if the card + * supports this. See the ::PCPS_GIVE_IRIG_TIME command. + * + * The granularity of the value in the ::PCPS_IRIG_TIME::frac field + * depends on the update interval at which the structure is updated + * by the firmeware. I.e., if the raw IRIG time is updated only + * once per second, the ::PCPS_IRIG_TIME::frac value can always be 0. + * + * @see @ref group_icode + * @see ::ICODE_RX_CODES + */ +typedef struct { PCPS_TIME_STATUS_X status; ///< status bits, see @ref PCPS_TIME_STATUS_FLAGS - int16_t offs_utc; ///< [minutes] + int16_t offs_utc; ///< [minutes], 0 unless supported by the code format, see ::MSK_ICODE_RX_HAS_TZI uint16_t yday; ///< day of year, 1..365/366 uint16_t frac; ///< fractions of seconds, 0.1 ms units - uint8_t sec; ///< seconds, 0..59, or 60 if leap second + uint8_t sec; ///< seconds, 0..59, may be 60 for leap second uint8_t min; ///< minutes, 0..59 uint8_t hour; ///< hours, 0..23 - uint8_t year; ///< 2 digit year number, 0xFF if year not supp. by the IRIG code - PCPS_SIG_VAL signal; ///< signal strength, different meanings, see notes for @ref PCPS_SIG_VAL_DEFS + uint8_t year; ///< 2 digit year number, or ::IRIG_TIME_UNKNOWN_YEAR if year not supported + ///< by the time code, see ::MSK_ICODE_RX_HAS_ANY_SHORT_YEAR + PCPS_SIG_VAL signal; ///< signal strength, see @ref PCPS_SIG_VAL_DEFS uint8_t reserved; ///< currently not used, always 0 + } PCPS_IRIG_TIME; #define _mbg_swab_pcps_irig_time( _p ) \ +do \ { \ _mbg_swab_pcps_time_status_x( &(_p)->status ); \ _mbg_swab16( &(_p)->offs_utc ); \ _mbg_swab16( &(_p)->yday ); \ _mbg_swab16( &(_p)->frac ); \ -} +} while ( 0 ) + + +/** + * @brief A constant representing a 2 digit unknown IRIG year number + * + * Used with ::PCPS_IRIG_TIME::year + */ +#define IRIG_TIME_UNKNOWN_YEAR 0xFF @@ -1158,13 +1254,13 @@ typedef struct PCPS_IRIG_TIME_s 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 enabled + 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 + 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 was disconn'd, or absolute time can't be decoded safely + PCPS_INVT = 0x80 ///< invalid time because battery had been disconnected, or absolute time can't be decoded safely }; @@ -1203,7 +1299,6 @@ enum PCPS_TIME_STATUS_FLAGS_EXT * This flag is not supported by all clocks. */ PCPS_IO_BLOCKED = 0x8000 - }; @@ -1242,7 +1337,7 @@ enum PCPS_TIME_STATUS_FLAGS_EXT * shifted to the right position. ::PCPS_GET_SERIAL expects that parameter * byte and ::PCPS_GET_SERIAL returns the current configuration from * the board. - * _pcps_has_serial() checks whether supported. + * ::_pcps_has_serial checks whether supported. * For old GPS clocks refer to the comments for the ::PCPS_GET_SERIAL * command. */ @@ -1283,7 +1378,7 @@ enum PCPS_BD_CODES * ::MBG_FRAMING_CODES and associated structures * should be used preferably. * - * Unfortunately, these framing codes can *not* simply + * Unfortunately, these framing codes can ***not*** simply * be replaced by the newer MBG_FRAMING_... definitions * since the order of indices doesn't match. */ @@ -1344,11 +1439,11 @@ typedef uint8_t PCPS_TZCODE; */ enum PCPS_TZCODES { - PCPS_TZCODE_CET_CEST, /* default as broadcasted by DCF77 (UTC+1h/UTC+2h) */ - PCPS_TZCODE_CET, /* always CET (UTC+1h), discard DST */ - PCPS_TZCODE_UTC, /* always %UTC */ - PCPS_TZCODE_EET_EEST, /* East European Time, CET/CEST + 1h */ - N_PCPS_TZCODE /* the number of valid codes */ + PCPS_TZCODE_CET_CEST, ///< default as broadcast by DCF77 (UTC+1h/UTC+2h) + PCPS_TZCODE_CET, ///< always CET (UTC+1h), discard DST + PCPS_TZCODE_UTC, ///< always %UTC + PCPS_TZCODE_EET_EEST, ///< East European Time, CET/CEST + 1h + N_PCPS_TZCODE ///< the number of valid codes }; /* the definitions below are for compatibily only: */ @@ -1358,66 +1453,94 @@ enum PCPS_TZCODES /** - * 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. + * @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 { - // 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; + uint16_t year_or_wday; ///< The full year number, or 0..6 == Sun..Sat if the ::DL_AUTO_FLAG is set + uint8_t month; ///< [1..12] + uint8_t mday; ///< [1..31] + uint8_t hour; ///< [0..23] + uint8_t min; ///< [0..59] + } PCPS_DL_ONOFF; #define _mbg_swab_pcps_dl_onoff( _p ) \ +do \ { \ _mbg_swab16( &(_p)->year_or_wday ); \ -} +} while ( 0 ) /** - * 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. + * @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 + +/** + * @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] - int16_t offs_dl; ///< additional offset if DST enabled [min] + int16_t offs; ///< offset from %UTC to local time [min] (local time = %UTC + offs) + int16_t offs_dl; ///< additional offset if DST enabled [min] (DST time = local time + offs_dl) PCPS_DL_ONOFF tm_on; ///< date/time when daylight saving starts PCPS_DL_ONOFF tm_off; ///< date/time when daylight saving ends + } PCPS_TZDL; #define _mbg_swab_pcps_tzdl( _p ) \ +do \ { \ _mbg_swab16( &(_p)->offs ); \ _mbg_swab16( &(_p)->offs_dl ); \ _mbg_swab_pcps_dl_onoff( &(_p)->tm_on ); \ _mbg_swab_pcps_dl_onoff( &(_p)->tm_off ); \ -} +} while ( 0 ) +/** + * @brief Status of the time capture FIFO buffer + * + * Only supported if ::RECEIVER_INFO::n_ucaps > 0. + */ typedef struct { uint32_t used; ///< the number of saved capture events uint32_t max; ///< capture buffer size + } PCPS_UCAP_ENTRIES; #define _mbg_swab_pcps_ucap_entries( _p ) \ +do \ { \ _mbg_swab32( &(_p)->used ); \ _mbg_swab32( &(_p)->max ); \ -} +} while ( 0 ) @@ -1440,10 +1563,10 @@ typedef uint16_t TR_DISTANCE; ///< Range may vary with receiver type */ 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 '>' - PCPS_SIG_VAL signal; ///< signal strength, different meanings, see notes for @ref PCPS_SIG_VAL_DEFS + 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; @@ -1452,9 +1575,9 @@ typedef struct /** - * @brief Codes used with CORR_INFO::status: + * @brief Codes used with ::CORR_INFO::status */ -enum +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 @@ -1494,20 +1617,24 @@ enum /** * @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 + * Codes specifying various types of data that can be read from or + * written to Meinberg bus level devices which support this. + * Access is done using the low level functions ::pcps_read_gps + * and ::pcps_write_gps since the size of some of the structures * exceeds the size of the device's I/O buffer and must therefore be * accessed in several blocks. * + * Applications should instead use the API functions declared in mbgdevio.h. + * * The structures to be used are defined in gpsdefs.h. Not all structures - * are supported, yet. Check the R/W indicators for details. + * are supported, yet. Check the r/w indicators for details. + * + * @see @ref PCPS_CMD_CODES + * @see ::PC_GPS_CMD_CODES_TABLE */ enum PC_GPS_CMD_CODES { - // system data - PC_GPS_TZDL = 0, ///< (r/w) ::TZDL, time zone / daylight saving, only if ::GPS_MODEL_HAS_TZDL + PC_GPS_TZDL, ///< (r/w) ::TZDL, time zone / daylight saving, only if ::GPS_MODEL_HAS_TZDL PC_GPS_SW_REV, ///< (r/-) ::SW_REV, software revision, deprecated by ::PC_GPS_RECEIVER_INFO PC_GPS_BVAR_STAT, ///< (r/-) ::BVAR_STAT, status of buffered variables, only if ::GPS_MODEL_HAS_BVAR_STAT PC_GPS_TIME, ///< (r/w) ::TTM, current time, deprecated by ::PCPS_GIVE_HR_TIME @@ -1515,23 +1642,25 @@ enum PC_GPS_CMD_CODES 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_ANT_CABLE_LEN, ///< (r/w) ::ANT_CABLE_LEN, length of antenna cable, only if ::GPS_MODEL_HAS_ANT_CABLE_LEN PC_GPS_RECEIVER_INFO, ///< (r/-) ::RECEIVER_INFO, rcvr model info, only if ::PCPS_HAS_RECEIVER_INFO + PC_GPS_ALL_STR_TYPE_INFO, ///< (r/-) n * ::STR_TYPE_INFO_IDX, names and capabilities of all supp. string types, only if ::RECEIVER_INFO::n_str_type > 0 PC_GPS_ALL_PORT_INFO, ///< (r/-) n * ::PORT_INFO_IDX, settings and capabilities of all serial ports, only if ::RECEIVER_INFO::n_com_ports > 0 PC_GPS_PORT_SETTINGS_IDX, ///< (-/w) ::PORT_SETTINGS_IDX, settings for specified serial port, only if ::RECEIVER_INFO::n_com_ports > 0 - PC_GPS_ALL_POUT_INFO, ///< (r/-) n * ::POUT_INFO_IDX, all programmable output info PC_GPS_POUT_SETTINGS_IDX, ///< (-/w) ::POUT_SETTINGS_IDX, settings for one programmable output PC_GPS_TIME_SCALE, ///< (r/w) ::MBG_TIME_SCALE_SETTINGS / ::MBG_TIME_SCALE_INFO, only if ::PCPS_HAS_TIME_SCALE PC_GPS_LAN_IF_INFO, ///< (r/-) ::LAN_IF_INFO, LAN interface info, only if ::PCPS_HAS_LAN_INTF PC_GPS_IP4_STATE, ///< (r/-) ::IP4_SETTINGS, LAN interface state, only if ::PCPS_HAS_LAN_INTF + PC_GPS_IP4_SETTINGS, ///< (r/w) ::IP4_SETTINGS, LAN interface configuration, only if ::PCPS_HAS_LAN_INTF PC_GPS_PTP_STATE, ///< (r/-) ::PTP_STATE, only if ::PCPS_HAS_PTP PC_GPS_PTP_CFG, ///< (r/w) ::PTP_CFG_SETTINGS / ::PTP_CFG_INFO, only if ::PCPS_HAS_PTP @@ -1540,6 +1669,7 @@ enum PC_GPS_CMD_CODES 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 @@ -1548,7 +1678,10 @@ enum PC_GPS_CMD_CODES PC_GPS_ALL_XMR_INFO, ///< (r/-) n * ::XMULTI_REF_INFO_IDX, where n == ::XMULTI_REF_INSTANCES::n_xmr_settings, only if ::GPS_HAS_XMULTI_REF PC_GPS_ALL_XMR_STATUS, ///< (r/w) n * ::XMULTI_REF_STATUS_IDX, where n == ::XMULTI_REF_INSTANCES::n_xmr_settings, one structure on write, only if ::GPS_HAS_XMULTI_REF PC_GPS_XMR_HOLDOVER_STATUS, ///< (r/-) ::XMR_HOLDOVER_STATUS, only if ::XMRIF_MSK_HOLDOVER_STATUS_SUPP + PC_GPS_ALL_GPIO_STATUS, ///< (r/-) n * ::MBG_GPIO_STATUS_IDX, where n == ::MBG_GPIO_CFG_LIMITS::num_io, only if ::MBG_GPIO_CFG_LIMIT_FLAG_MASK_STATUS_SUPP + PC_GPS_XFEATURE_BUFFER, ///< (r/-) ::MBG_XFEATURE_BUFFER, only if ::GPS_HAS_XFEATURE + PC_GPS_TLV_INFO, ///< (r/-) ::MBG_TLV_INFO, only if ::MBG_XFEATURE_TLV_API // GPS data PC_GPS_CFGH = 0x80, ///< (-/-) ::CFGH, SVs' config. and health codes (yet not used) @@ -1566,8 +1699,10 @@ enum PC_GPS_CMD_CODES * * This can e.g. be assigned to an array of ::MBG_CODE_NAME_TABLE_ENTRY elements * and may be helpful when debugging. + * + * @see ::PC_GPS_CMD_CODES */ -#define MBG_PC_GPS_CMD_TABLE \ +#define PC_GPS_CMD_CODES_TABLE \ { \ _mbg_cn_table_entry( PC_GPS_TZDL ), \ _mbg_cn_table_entry( PC_GPS_SW_REV ), \ @@ -1610,6 +1745,9 @@ enum PC_GPS_CMD_CODES _mbg_cn_table_entry( PC_GPS_ALL_XMR_STATUS ), \ _mbg_cn_table_entry( PC_GPS_XMR_HOLDOVER_STATUS ), \ _mbg_cn_table_entry( PC_GPS_ALL_GPIO_STATUS ), \ + _mbg_cn_table_entry( PC_GPS_XFEATURE_BUFFER ), \ + _mbg_cn_table_entry( PC_GPS_TLV_INFO ), \ + \ _mbg_cn_table_entry( PC_GPS_CFGH ), \ _mbg_cn_table_entry( PC_GPS_ALM ), \ _mbg_cn_table_entry( PC_GPS_EPH ), \ @@ -1623,10 +1761,12 @@ enum PC_GPS_CMD_CODES /** * @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_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 @@ -1635,12 +1775,17 @@ enum PC_GPS_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; @@ -1649,8 +1794,6 @@ typedef uint16_t PCPS_CMD_INFO; #undef _USING_BYTE_ALIGNMENT #endif -#define _PCPSDEFS_H_INCLUDED - /* End of header body */ #endif /* _PCPSDEFS_H */ diff --git a/c/mbglib/include/pcpsdev.h b/c/mbglib/include/pcpsdev.h index 1d6694e..9e3a048 100644 --- a/c/mbglib/include/pcpsdev.h +++ b/c/mbglib/include/pcpsdev.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: pcpsdev.h 1.53.1.8 2014/05/23 09:48:55Z martin TRASH martin $ + * $Id: pcpsdev.h 1.60 2019/07/31 15:44:31Z martin TRASH $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -17,19 +17,46 @@ * * ----------------------------------------------------------------------- * $Log: pcpsdev.h $ - * Revision 1.53.1.8 2014/05/23 09:48:55Z martin - * Revision 1.53.1.7 2014/05/22 14:53:34 martin - * Added _pcps_has_ri_xmr() macro. - * Revision 1.53.1.6 2014/04/15 15:37:47 martin - * Support GPIO ports. - * Revision 1.53.1.5 2014/01/23 15:35:48 martin + * Revision 1.60 2019/07/31 15:44:31Z martin + * Doxygen changes. + * Revision 1.59 2019/05/08 11:27:36 martin + * Use new symbol PCPS_IRQ_NUM_UNDEFINED. + * Revision 1.58 2018/11/02 14:58:43 martin + * Updated a comment. + * Revision 1.57 2018/09/21 15:04:23 martin + * Added definitions for TCR180USB. + * Added define MBG_DEV_NAME_FMT and macro _tlv_feat_buffp(); + * Defined a print format for firmware versions. + * Renamed macro _must_do_fw_workaround_20ms() + * to _pcps_fw_has_20ms_bug(). + * More unified resource handling. + * Renamed a number of symbols. + * Updated naming for device feature stuff. + * Added doxygen comments. + * Revision 1.56 2017/07/04 16:31:08 martin + * New types PCPS_CLOCK_NAME and MBG_DEV_NAME. + * Definitions used with new feature check implementation. + * Changed some macros and definitions to clean up + * I/O port usage and storage. + * Moved some definitions used with IOCTLs to mbgioctl.h. + * Revision 1.55 2017/04/25 11:36:40 martin + * Renamed GRC181PEX to GNS181PEX. + * Revision 1.54 2017/01/27 09:10:57 martin * Support GPS180AMC. - * Revision 1.53.1.4 2013/12/18 14:52:15 martin + * Support GRC181PEX. + * Support GPIO ports. + * IRIG TX support for GPS180PEX and TCR180PEX only + * if GPS_HAS_IRIG_TX flag is set. + * New type PCPS_FW_REV_NUM. + * Moved some code to new module mbgsystm.h. + * Moved NANO_TIME_64 to gpsdefs.h. * Moved inline function num_bits_set() to cfg_hlp.h. - * Revision 1.53.1.3 2013/12/16 10:39:35 martin - * Revision 1.53.1.2 2013/12/12 11:58:09Z martin - * Revision 1.53.1.1 2013/12/12 11:29:17Z martin + * Added macro _ri_addr(). + * Added macro _pcps_has_ri_xmr(). + * Fixed macro syntax. * Doxygen stuff. + * Removed trailing spaces. + * Cleanup. * Revision 1.53 2013/11/08 08:46:00 martin * Doxygen comment updates. * Revision 1.52 2013/09/26 09:06:47Z martin @@ -106,7 +133,7 @@ * Moved some inline functions dealing with MBG_PC_CYCLES * from mbgdevio.h here. * Merged the code from _pcps_get_cycles() and _pcps_get_cycles_frequency() - * to the mbg_get_pc_cycles...() inline functions which now replace the + * to the mbg_get_pc_cycles...() inline functions which now replace the * _pcps_get_cycles...() macros. * Fixed cycles code for non-x86 architectures. * Revision 1.39 2008/12/05 16:24:24Z martin @@ -117,7 +144,7 @@ * Defined firmware version numbers which fix an IRQ problem with PEX511, * TCR511PEX, and GPS170PEX cards. The fix also requires specific ASIC * versions specified in pci_asic.h. - * Defined firmware versions at which PCI511 and PEX511 start + * Defined firmware versions at which PCI511 and PEX511 start * to support HR time. * Support mapped I/O resources. * Changed MBG_PC_CYCLES type for Windows to int64_t. @@ -137,11 +164,11 @@ * _psps_has_asic_version(), _pcps_has_asic_features(). * Revision 1.37 2008/01/17 09:58:11Z daniel * Made comments compatible for doxygen parser. - * No sourcecode changes. + * No sourcecode changes. * Revision 1.36 2007/09/26 09:34:38Z martin * Added support for USB in general and new USB device USB5131. * Added new types PCPS_DEV_ID and PCPS_REF_TYPE. - * Removed old PCPS_ERR_... codes. Use MBG_ERR_... codes + * Removed old PCPS_ERR_... codes. Use MBG_ERR_... codes * from mbgerror.h instead. The old values haven't changed. * Revision 1.35 2007/07/17 08:22:47Z martin * Added support for TCR511PEX and GPS170PEX. @@ -154,15 +181,15 @@ * Preliminary support for *BSD. * Preliminary support for USB. * Revision 1.32 2006/10/23 08:47:55Z martin - * Don't use abs() in _pcps_ref_offs_out_of_range() since this might + * Don't use abs() in _pcps_ref_offs_out_of_range() since this might * not work properly for 16 bit integers and value 0x8000. * Revision 1.31 2006/06/14 12:59:13Z martin * Added support for TCR511PCI. * Revision 1.30 2006/04/05 14:58:41 martin * Support higher baud rates for PCI511. * Revision 1.29 2006/04/03 07:29:07Z martin - * Added a note about the missing PCPS_ST_IRQF signal - * on PCI510 cards. + * Added a note about the missing PCPS_ST_IRQF signal + * on PCI510 cards. * Revision 1.28 2006/03/10 10:32:56Z martin * Added support for PCI511. * Added support for programmable pulse outputs. @@ -183,8 +210,8 @@ * New type PCPS_STATUS_PORT. * Removed obsolete inclusion of asm/timex.h for Linux. * Revision 1.21 2004/09/06 15:19:49Z martin - * Support a GPS_DATA interface where sizes are specified - * by 16 instead of the original 8 bit quantities, thus allowing + * Support a GPS_DATA interface where sizes are specified + * by 16 instead of the original 8 bit quantities, thus allowing * to transfer data blocks which exceed 255 bytes. * Modified inclusion of header files under Linux. * Modified definition of MBG_PC_CYCLES for Linux. @@ -263,6 +290,7 @@ #include <mbg_tgt.h> #include <mbgtime.h> +#include <mbgsystm.h> #include <mbgpccyc.h> #include <pcpsdefs.h> #include <gpsdefs.h> @@ -273,20 +301,10 @@ #include <string.h> #endif -#if defined( MBG_TGT_WIN32 ) - - #include <mbg_w32.h> - -#elif defined( MBG_TGT_LINUX ) +#if defined( MBG_TGT_LINUX ) - #if defined( MBG_TGT_KERNEL ) - #include <linux/delay.h> - #include <linux/time.h> - #else + #if !defined( MBG_TGT_KERNEL ) #include <unistd.h> - #include <time.h> - #include <sys/time.h> - #include <sys/sysinfo.h> #endif #elif defined( MBG_TGT_FREEBSD ) @@ -304,10 +322,7 @@ #elif defined( MBG_TGT_NETBSD ) - #if defined( MBG_TGT_KERNEL ) - #include <sys/param.h> // mstohz - #include <sys/kernel.h> // hz - #else + #if !defined( MBG_TGT_KERNEL ) #include <unistd.h> #include <sys/time.h> #endif @@ -333,97 +348,32 @@ #endif -#if defined( MBG_TGT_UNIX ) - #define USE_GENERIC_SYS_TIME 1 -#else - #define USE_GENERIC_SYS_TIME 0 -#endif - - -#if USE_GENERIC_SYS_TIME - - typedef struct - { - uint64_t sec; - uint64_t nsec; - } NANO_TIME_64; - - typedef NANO_TIME_64 MBG_SYS_TIME; - -#endif - - - -/** - Define generic types to hold PC cycle counter values and system timestamps. - The generic types are defined using native types used by the target operating - systems. - - The cycle counter value is usually derived from the PC CPU's TSC or some other - timer hardware on the mainboard. - */ -#if defined( MBG_TGT_WIN32 ) - - #define MBG_TGT_SUPP_MEM_ACC 1 - - typedef int64_t MBG_SYS_UPTIME; // [s] - - typedef LARGE_INTEGER MBG_SYS_TIME; - -#elif defined( MBG_TGT_LINUX ) +#if defined( MBG_TGT_LINUX ) #define MBG_TGT_SUPP_MEM_ACC 1 - typedef int64_t MBG_SYS_UPTIME; // [s] - #elif defined( MBG_TGT_BSD ) #define MBG_TGT_SUPP_MEM_ACC 1 - typedef int64_t MBG_SYS_UPTIME; // [s] - - #if defined( MBG_TGT_NETBSD ) - #ifdef __LP64__ - #define MBG_MEM_ADDR uint64_t - #else - #define MBG_MEM_ADDR uint32_t - #endif - #endif - -#elif defined( MBG_TGT_OS2 ) - - typedef long MBG_SYS_UPTIME; //## dummy +#elif defined( MBG_TGT_WIN32 ) - typedef uint32_t MBG_SYS_TIME; //## dummy + #define MBG_TGT_SUPP_MEM_ACC 1 #elif defined( MBG_TGT_DOS ) - #define MBG_MEM_ADDR uint32_t // 64 bit not supported, nor required. - - typedef long MBG_SYS_UPTIME; //## dummy - - typedef uint32_t MBG_SYS_TIME; //## dummy - -#else // other target OSs which access the hardware directly - - typedef long MBG_SYS_UPTIME; //## dummy - - typedef uint32_t MBG_SYS_TIME; //## dummy - #endif -// MBG_SYS_TIME is always read in native machine endianess, -// so no need to convert endianess. -#define _mbg_swab_mbg_sys_time( _p ) \ - _nop_macro_fnc() - - #if !defined( MBG_TGT_SUPP_MEM_ACC ) #define MBG_TGT_SUPP_MEM_ACC 0 #endif +typedef uint8_t MBG_DBG_DATA; +typedef uint16_t MBG_DBG_PORT; + + /** * @brief System time plus associated cycles counter values @@ -442,310 +392,32 @@ typedef struct MBG_PC_CYCLES cyc_before; ///< cycles count before sys time is read MBG_PC_CYCLES cyc_after; ///< cycles count after sys time has been read MBG_SYS_TIME sys_time; ///< system time stamp + } MBG_SYS_TIME_CYCLES; #define _mbg_swab_mbg_sys_time_cycles( _p ) \ +do \ { \ _mbg_swab_mbg_pc_cycles( &(_p)->cyc_before ); \ _mbg_swab_mbg_pc_cycles( &(_p)->cyc_after ); \ _mbg_swab_mbg_sys_time( &(_p)->sys_time ); \ -} - +} while ( 0 ) -static __mbg_inline -void mbg_get_sys_time( MBG_SYS_TIME *p ) -{ - #if defined( MBG_TGT_WIN32 ) - - #if defined( MBG_TGT_KERNEL ) // kernel space - #if defined( MBG_TGT_WIN32_PNP ) && !defined( MBG_TGT_WIN32_PNP_X64 ) - extern KE_QUERY_SYSTEM_TIME_FNC ke_query_system_time_fnc; - ke_query_system_time_fnc( p ); - #else - KeQuerySystemTime( p ); - #endif - #else // user space - { - FILETIME ft; - GetSystemTimeAsFileTime( &ft ); - p->LowPart = ft.dwLowDateTime; - p->HighPart = ft.dwHighDateTime; - } - #endif - - #elif defined( MBG_TGT_LINUX ) - - #if defined( MBG_TGT_KERNEL ) - - #if ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 22 ) ) //##+++++++++++++ - { - // getnstimeofday() supported - struct timespec ts; - - getnstimeofday( &ts ); - - p->sec = ts.tv_sec; - p->nsec = ts.tv_nsec; - } - #else - { - // getnstimeofday() *not* supported - struct timeval tv; - - do_gettimeofday( &tv ); - - p->sec = tv.tv_sec; - p->nsec = tv.tv_usec * 1000; - } - #endif - - #else // Linux user space - { - struct timespec ts; - - clock_gettime( CLOCK_REALTIME, &ts ); - - p->sec = ts.tv_sec; - p->nsec = ts.tv_nsec; - } - #endif - - #elif defined( MBG_TGT_BSD ) - - struct timespec ts; - - #if defined( MBG_TGT_KERNEL ) - nanotime( &ts ); - #else - #if defined( MBG_TGT_FREEBSD ) - clock_gettime( CLOCK_REALTIME_PRECISE, &ts ); - #else // MBG_TGT_NETBSD, ... - clock_gettime( CLOCK_REALTIME, &ts ); - #endif - #endif - - p->sec = ts.tv_sec; - p->nsec = ts.tv_nsec; - - #else - - *p = 0; - - #endif - -} // mbg_get_sys_time - - - -static __mbg_inline -void mbg_get_sys_uptime( MBG_SYS_UPTIME *p ) -{ - #if defined( MBG_TGT_WIN32 ) - - #if defined( MBG_TGT_KERNEL ) // kernel space - - ULONGLONG time_increment = KeQueryTimeIncrement(); - LARGE_INTEGER tick_count; - - KeQueryTickCount( &tick_count ); - - // multiplication by time_increment yields HNS units, - // but we need seconds - *p = ( tick_count.QuadPart * time_increment ) / HNS_PER_SEC; - - #else // user space - - DWORD tickCount; - DWORD timeAdjustment; - DWORD timeIncrement; - BOOL timeAdjustmentDisabled; - - if ( !GetSystemTimeAdjustment( &timeAdjustment, &timeIncrement, &timeAdjustmentDisabled ) ) - *p = -1; // failed - - // ATTENTION: This is compatible with older Windows versions, but - // the returned tick count wraps around to zero after 49.7 days. - // A new GetTickCount64() call is available under Windows Vista and newer, - // but the function call had to be imported dynamically since otherwise - // programs refused to start under pre-Vista versions due to undefined DLL symbol. - tickCount = GetTickCount(); - - *p = ( ( (MBG_SYS_UPTIME) tickCount ) * timeIncrement ) / HNS_PER_SEC; - - #endif - - #elif defined( MBG_TGT_LINUX ) - - #if defined( MBG_TGT_KERNEL ) - // getrawmonotonic() can possibly be used for this in newer kernels - { - // Using a simple 64 bit division may result in a linker error - // in kernel mode due to a missing symbol __udivdi3, so we use - // a specific inline function do_div(). - // Also, the jiffies counter is not set to 0 at startup but to - // a defined initialization value we need to account for. - uint64_t tmp = get_jiffies_64() - INITIAL_JIFFIES; - do_div( tmp, HZ ); - *p = tmp; - } - #else - { - struct sysinfo si; - int rc = sysinfo( &si ); - *p = ( rc == 0 ) ? si.uptime : -1; - } - #endif - - #elif defined( MBG_TGT_BSD ) - - #if defined( MBG_TGT_KERNEL ) - { - struct timespec ts; - #if 0 //##+++++++ - { - struct bintime bt; - - binuptime( &bt ); - #if defined( DEBUG ) - printf( "binuptime: %lli.%09lli\n", - (long long) bt.sec, - (long long) bt.frac ); - #endif - } - #endif - - nanouptime( &ts ); - #if defined( DEBUG ) - printf( "nanouptime: %lli.%09lli\n", - (long long) ts.tv_sec, - (long long) ts.tv_nsec ); - #endif - *p = ts.tv_sec; - } - #elif defined( MBG_TGT_FREEBSD ) - { - struct timespec ts; - // CLOCK_UPTIME_FAST is specific to FreeBSD - int rc = clock_gettime( CLOCK_UPTIME_FAST, &ts ); - *p = ( rc == 0 ) ? ts.tv_sec : -1; - } - #else // MBG_TGT_NETBSD, ... - - *p = -1; //##++ needs to be implemented - - #endif - - #else - - *p = -1; // not supported - - #endif - -} // mbg_get_sys_uptime - - - -static __mbg_inline -void mbg_sleep_sec( long sec ) -{ - #if defined( MBG_TGT_WIN32 ) - - #if defined( MBG_TGT_KERNEL ) // kernel space - LARGE_INTEGER delay; - - // we need to pass a negative value to KeDelayExecutionThread() - // since the given time is a relative time interval, not absolute - // time. See the API docs for KeDelayExecutionThread(). - delay.QuadPart = - ((LONGLONG) sec * HNS_PER_SEC); - - KeDelayExecutionThread( KernelMode, FALSE, &delay ); - #else // user space - // Sleep() expects milliseconds - Sleep( sec * 1000 ); - #endif - - #elif defined( MBG_TGT_LINUX ) - - #if defined( MBG_TGT_KERNEL ) - // msleep is not defined in older kernels, so we use this - // only if it is surely supported. - #if ( LINUX_VERSION_CODE >= KERNEL_VERSION( 2, 6, 16 ) ) //##+++++ - msleep( sec * 1000 ); - #else - { - DECLARE_WAIT_QUEUE_HEAD( tmp_wait ); - wait_event_interruptible_timeout( tmp_wait, 0, sec * HZ + 1 ); - } - #endif - #else - sleep( sec ); - #endif - - #elif defined( MBG_TGT_BSD ) - - #if defined( MBG_TGT_KERNEL ) - #if defined( MBG_TGT_FREEBSD ) - struct timeval tv = { 0 }; - int ticks; - tv.tv_sec = sec; - ticks = tvtohz( &tv ); - #if defined( DEBUG ) - printf( "pause: %lli.%06lli (%i ticks)\n", - (long long) tv.tv_sec, - (long long) tv.tv_usec, - ticks ); - #endif - pause( "pause", ticks ); - #elif defined( MBG_TGT_NETBSD ) - int timeo = mstohz( sec * 1000 ); - #if defined( DEBUG ) - printf( "kpause: %i s (%i ticks)\n", sec, timeo ); - #endif - kpause( "pause", 1, timeo, NULL ); - #endif - #else - sleep( sec ); - #endif - - #elif defined( MBG_TGT_QNX_NTO ) - - // Actually only tested under Neutrino. - sleep( sec ); - - #elif defined( MBG_TGT_DOS ) - - delay( (unsigned) ( sec * 1000 ) ); - - #else - - // This needs to be implemented for the target OS - // and thus will probably yield a linker error. - do_sleep_sec( sec ); - - #endif - -} // mbg_sleep_sec - - - -#if !defined( MBG_MEM_ADDR ) - // By default a memory address is stored - // as a 64 bit quantitiy. - #define MBG_MEM_ADDR uint64_t -#endif - - -typedef uint8_t MBG_DBG_DATA; -typedef uint16_t MBG_DBG_PORT; +/** + * @defgroup group_bus_flag_masks BUS flag masks + * + * @anchor PCPS_BUS_FLAG_MASKS + * + * @{ */ // The following flags describe the bus types which are // supported by the plugin clocks. -#define PCPS_BUS_ISA 0x0001 // IBM compatible PC/AT ISA bus -#define PCPS_BUS_MCA 0x0002 // IBM PS/2 micro channel -#define PCPS_BUS_PCI 0x0004 // PCI -#define PCPS_BUS_USB 0x0008 // USB +#define PCPS_BUS_ISA 0x0001 ///< IBM compatible PC/AT ISA bus +#define PCPS_BUS_MCA 0x0002 ///< IBM PS/2 micro channel +#define PCPS_BUS_PCI 0x0004 ///< PCI +#define PCPS_BUS_USB 0x0008 ///< USB // The flags below are or'ed to the PC_BUS_PCI code @@ -753,10 +425,10 @@ typedef uint16_t MBG_DBG_PORT; // on a PCI card. If no flag is set then the S5933 chip is // installed which has been used for the first generation // of Meinberg PCI cards. -#define PCPS_BUS_PCI_CHIP_S5920 0x8000 // S5920 PCI interface chip. -#define PCPS_BUS_PCI_CHIP_ASIC 0x4000 // Meinberg's own PCI interface chip. -#define PCPS_BUS_PCI_CHIP_PEX8311 0x2000 // PEX8311 PCI Express interface chip -#define PCPS_BUS_PCI_CHIP_MBGPEX 0x1000 // Meinberg's own PCI Express interface chip +#define PCPS_BUS_PCI_CHIP_S5920 0x8000 ///< S5920 PCI interface chip. +#define PCPS_BUS_PCI_CHIP_ASIC 0x4000 ///< Meinberg's own PCI interface chip. +#define PCPS_BUS_PCI_CHIP_PEX8311 0x2000 ///< PEX8311 PCI Express interface chip +#define PCPS_BUS_PCI_CHIP_MBGPEX 0x1000 ///< Meinberg's own PCI Express interface chip // The constants below combine the PCI bus flags: #define PCPS_BUS_PCI_S5933 ( PCPS_BUS_PCI ) @@ -775,6 +447,8 @@ typedef uint16_t MBG_DBG_PORT; // The constant below combines the PCI bus flags: #define PCPS_BUS_USB_V2 ( PCPS_BUS_USB | PCPS_BUS_USB_FLAG_V2 ) +/** @} defgroup group_bus_flag_masks */ + /** @@ -817,12 +491,16 @@ enum PCPS_TYPES PCPS_TYPE_WVB600USB, PCPS_TYPE_GLN180PEX, PCPS_TYPE_GPS180AMC, + PCPS_TYPE_GNS181PEX, + PCPS_TYPE_TCR180USB, N_PCPS_DEV_TYPE }; #define PCPS_CLOCK_NAME_SZ 10 // including terminating 0 +typedef char PCPS_CLOCK_NAME[PCPS_CLOCK_NAME_SZ]; + typedef uint16_t PCPS_DEV_ID; typedef uint16_t PCPS_REF_TYPE; typedef uint16_t PCPS_BUS_FLAGS; @@ -837,31 +515,43 @@ typedef uint16_t PCPS_BUS_FLAGS; */ typedef struct { - uint16_t num; - char name[PCPS_CLOCK_NAME_SZ]; - PCPS_DEV_ID dev_id; - PCPS_REF_TYPE ref_type; - PCPS_BUS_FLAGS bus_flags; -} PCPS_DEV_TYPE; + uint16_t num; ///< see ::PCPS_TYPES + PCPS_CLOCK_NAME name; + PCPS_DEV_ID dev_id; ///< see @ref MEINBERG_PCI_DEVICE_IDS and @ref MBG_USB_DEVICE_IDS + PCPS_REF_TYPE ref_type; ///< see ::PCPS_REF_TYPES + PCPS_BUS_FLAGS bus_flags; ///< see @ref PCPS_BUS_FLAG_MASKS +} PCPS_DEV_TYPE; -#if !defined( MBG_TGT_UNIX ) || defined( MBG_ARCH_X86 ) - typedef uint16_t PCPS_PORT_ADDR; -#else - typedef uint64_t PCPS_PORT_ADDR; -#endif +/** + * @brief Legacy I/O address type, see ::PCPS_SHORT_PORT_RSRC + */ +typedef uint16_t PCPS_SHORT_PORT_ADDR; /** * @brief An I/O port resource used by a device + * + * This structure has originally been used to store information + * on an I/O address range. + * However, the 16 bits provided by ::PCPS_SHORT_PORT_ADDR may + * not be sufficient to hold an address on some target platforms, + * so this is only kept to maintain API compatibility when + * reporting I/O addresses to user space via ::PCPS_DEV_CFG + * and thus ::PCPS_DEV structures. + * A different structure is actually being used internally + * by the kernel drivers. */ typedef struct { - PCPS_PORT_ADDR base; + PCPS_SHORT_PORT_ADDR base; uint16_t num; -} PCPS_PORT_RSRC; + +} PCPS_SHORT_PORT_RSRC; + + /** * @brief The max. number of I/O port resources used by a clock @@ -870,47 +560,66 @@ typedef struct +/** + * @brief A structure used to retrieve an address to be mapped into user space + * + * @note This is currently not really supported and probably doesn't work. + */ typedef struct { - MBG_MEM_ADDR user_virtual_address; + void *user_virtual_address; // TODO #if defined( MBG_TGT_LINUX ) uint64_t len; uint64_t pfn_offset; #else ulong len; #endif + } PCPS_MAPPED_MEM; -typedef uint32_t PCPS_ERR_FLAGS; ///< see @ref PCPS_ERR_FLAG_MASKS -typedef uint32_t PCPS_FEATURES; ///< see @ref PCPS_FEATURE_MASKS +typedef uint32_t PCPS_ERR_FLAGS; ///< see @ref PCPS_ERR_FLAG_MASKS +typedef uint32_t PCPS_FEATURES; ///< see @ref PCPS_FEATURE_MASKS typedef uint16_t PCPS_BUS_NUM; typedef uint16_t PCPS_SLOT_NUM; +typedef uint16_t PCPS_FW_REV_NUM; ///< firmware revision number, MSB major, LSB minor version + +#define PCPS_IRQ_NUM_UNDEFINED -1 ///< Indicates the IRQ number is undefined. + + /** * @brief Device information * - * Contains data which depends on a particular instance - * of a device, e.g. the firmware which is currently installed, - * the port address which has actually been assigned, etc. + * Contains variable device data which depends on a particular instance + * of a device, e.g. the firmware which is currently installed, the + * port address which has actually been assigned, etc. + * + * @note This structure only contains an incomplete subset of + * information for newer devices, e.g. no memory resources, + * and no extended device features. + * However, adding the missing information would break + * compatibility of some API functions. */ typedef struct { PCPS_ERR_FLAGS err_flags; ///< See @ref PCPS_ERR_FLAG_MASKS PCPS_BUS_NUM bus_num; PCPS_SLOT_NUM slot_num; - PCPS_PORT_RSRC port[N_PCPS_PORT_RSRC]; - uint16_t status_port; - int16_t irq_num; + PCPS_SHORT_PORT_RSRC port[N_PCPS_PORT_RSRC]; + PCPS_SHORT_PORT_ADDR short_status_port; + int16_t irq_num; ///< ::PCPS_IRQ_NUM_UNDEFINED if undefined uint32_t timeout_clk; - uint16_t fw_rev_num; + PCPS_FW_REV_NUM fw_rev_num; PCPS_FEATURES features; ///< See @ref PCPS_FEATURE_MASKS PCPS_ID_STR fw_id; PCPS_SN_STR sernum; + } PCPS_DEV_CFG; + /** * @brief Possible device initialization error flags * @@ -925,22 +634,25 @@ typedef struct #define PCPS_EF_IO_INIT 0x00000004 ///< I/O interface not initialized #define PCPS_EF_IO_CFG 0x00000008 ///< I/O interface not configured #define PCPS_EF_IO_ENB 0x00000010 ///< I/O interface not enabled -#define PCPS_EF_IO_RSRC 0x00000020 ///< I/O resource not registered with resource manager +#define PCPS_EF_IO_RSRC_IO 0x00000020 ///< I/O resource not registered with resource manager +#define PCPS_EF_IO_RSRC_MEM 0x00000040 ///< Memory resource not registered with resource manager /** @} anchor PCPS_ERR_FLAG_MASKS */ + /** - * @defgroup group_pcps_features Feature flags used with ::PCPS_FEATURES + * @defgroup group_pcps_features Feature flags used with PCPS_FEATURES * * Some features of the radio clocks have been introduced with * specific firmware versions, so depending on the firmware version * a clock may support a feature or not. The clock detection function * checks the clock model and firmware version and updates the field - * PCPS_DEV_CFG::features accordingly. There are some macros which + * ::PCPS_DEV_CFG::features accordingly. There are some macros which * can easily be used to query whether a clock device actually - * supports a function, or not. The definitions define - * the possible features. + * supports a function, or not. + * + * @see ::PCPS_FEATURES * * @{ */ @@ -993,8 +705,9 @@ enum PCPS_FEATURE_BITS /** * @brief Feature bit masks for bus-level devices * - * Used with ::PCPS_DEV_CFG::err_flags + * Used with ::PCPS_DEV_CFG::features * + * @see ::PCPS_FEATURE_BITS * @see ::PCPS_FEATURES * * @anchor PCPS_FEATURE_MASKS @{ */ @@ -1187,9 +900,13 @@ enum PCPS_FEATURE_BITS #define PCPS_FEAT_WWVB51USB ( PCPS_FEAT_MSF51USB ) -#define PCPS_FEAT_GPS180PEX ( PCPS_FEAT_GPS170PEX | PCPS_HAS_FAST_HR_TSTAMP ) +#define PCPS_FEAT_GPS180PEX ( ( PCPS_FEAT_GPS170PEX | PCPS_HAS_FAST_HR_TSTAMP ) \ + & ~PCPS_HAS_IRIG_TX ) + ///< IRIG TX only supp. if ::GPS_HAS_IRIG_TX -#define PCPS_FEAT_TCR180PEX ( PCPS_FEAT_TCR170PEX | PCPS_HAS_FAST_HR_TSTAMP ) +#define PCPS_FEAT_TCR180PEX ( ( PCPS_FEAT_TCR170PEX | PCPS_HAS_FAST_HR_TSTAMP ) \ + & ~PCPS_HAS_IRIG_TX ) + ///< IRIG TX only supp. if ::GPS_HAS_IRIG_TX #define PCPS_FEAT_DCF600USB ( PCPS_FEAT_USB5131 ) @@ -1218,6 +935,19 @@ enum PCPS_FEATURE_BITS #define PCPS_FEAT_GPS180AMC ( PCPS_FEAT_GPS180PEX ) +#define PCPS_FEAT_GNS181PEX ( PCPS_FEAT_GLN180PEX ) + +#define PCPS_FEAT_TCR180USB ( PCPS_FEAT_TCR600USB \ + | PCPS_HAS_TZDL \ + | PCPS_HAS_RECEIVER_INFO \ + | PCPS_HAS_GPS_DATA_16 \ + | PCPS_CAN_CLR_UCAP_BUFF /* TODO ? */ \ + | PCPS_HAS_UCAP /* TODO ? */ \ + | PCPS_HAS_GENERIC_IO /* TODO ? */ ) + ///< IRIG TX only supp. if ::GPS_HAS_IRIG_TX + + + // Some features of the API used to access Meinberg plug-in devices // have been implemented starting with the special firmware revision // numbers defined below. @@ -1227,12 +957,12 @@ enum PCPS_FEATURE_BITS // There are some versions of PCI Express cards out there which do not -// safely support hardware IRQs. The following firmware versions are required +// safely support hardware IRQs. The following firmware versions are required // for safe IRQ operation: #define REV_HAS_IRQ_FIX_MINOR_PEX511 0x0106 #define REV_HAS_IRQ_FIX_MINOR_TCR511PEX 0x0105 #define REV_HAS_IRQ_FIX_MINOR_GPS170PEX 0x0104 -// Additionally there are certain revisions of the bus interface logic +// Additionally there are certain revisions of the bus interface logic // required. The associated version codes are defined in pci_asic.h. // The macro below can be used to check whether the required versions are there: @@ -1257,8 +987,8 @@ enum PCPS_FEATURE_BITS #define REV_HAS_IRIG_CTRL_BITS_TCR511PCI 0x0107 #define REV_HAS_IRIG_CTRL_BITS_TCR51USB 0x0106 -/* This board uses the GPS_DATA interface with 16 bit buffer sizes - instead of the original 8 bit sizes, thus allowing to transfer +/* This board uses the GPS_DATA interface with 16 bit buffer sizes + instead of the original 8 bit sizes, thus allowing to transfer data blocks which exceed 255 bytes (PCPS_HAS_GPS_DATA_16) */ #define REV_HAS_GPS_DATA_16_GPS169PCI 0x0202 @@ -1322,9 +1052,17 @@ typedef struct { PCPS_DEV_TYPE type; PCPS_DEV_CFG cfg; + } PCPS_DEV; +#if 1 || defined( MBG_TGT_KERNEL ) //### FIXME + #define _USE_DEV_MACROS 1 +#else + #define _USE_DEV_MACROS 0 +#endif + + // The macros below simplify access to the data // stored in PCPS_DEV structure and should be used // to extract the desired information. @@ -1372,12 +1110,11 @@ typedef struct #define _pcps_bus_num( _d ) ( (_d)->cfg.bus_num ) #define _pcps_slot_num( _d ) ( (_d)->cfg.slot_num ) -#define _pcps_cfg_port_rsrc( _c, _n ) ( (_c)->port[_n] ) -#define _pcps_port_rsrc( _d, _n ) _pcps_cfg_port_rsrc( &(_d)->cfg, (_n) ) -#define _pcps_port_rsrc_unused( _d ) ( (_d)->base == 0 || (_d)->num == 0 ) +#define _pcps_cfg_short_port_rsrc( _c, _n ) ( (_c)->port[_n] ) +#define _pcps_short_port_rsrc( _d, _n ) _pcps_cfg_short_port_rsrc( &(_d)->cfg, (_n) ) -#define _pcps_cfg_port_base( _c, _n ) ( _pcps_cfg_port_rsrc( (_c), (_n) ).base ) -#define _pcps_port_base( _d, _n ) ( _pcps_port_rsrc( (_d), (_n) ).base ) +#define _pcps_cfg_short_port_base( _c, _n ) ( _pcps_cfg_short_port_rsrc( (_c), (_n) ).base ) +#define _pcps_short_port_base( _d, _n ) ( _pcps_short_port_rsrc( (_d), (_n) ).base ) #define _pcps_cfg_irq_num( _c ) ( (_c)->irq_num ) #define _pcps_irq_num( _d ) _pcps_cfg_irq_num( &(_d)->cfg ) @@ -1398,12 +1135,19 @@ typedef struct #define _pcps_clr_err_flags( _d, _msk ) ( _pcps_err_flags( _d ) &= ~(_msk) ) +#if _USE_DEV_MACROS + /// Check whether a special feature is supported #define _pcps_has_feature( _d, _f ) ( ( (_d)->cfg.features & (_f) ) != 0 ) /// Check whether a special feature is supported according to ::RECEIVER_INFO #define _pcps_has_ri_feature( _p_ri, _f ) ( ( (_p_ri)->features & (_f) ) != 0 ) +#define _ri_addr( _p ) &(_p)->xdev_features.receiver_info +#define _xfeat_addr( _p ) &(_p)->xdev_features.xfeature_buffer +#define _tlv_info_addr( _p ) &(_p)->xdev_features.tlv_info +#define _tlv_feat_buffp( _p ) &(_p)->xdev_features.tlv_info.supp_tlv_feat + #define _pcps_can_set_time( _d ) _pcps_has_feature( (_d), PCPS_CAN_SET_TIME ) #define _pcps_has_serial( _d ) _pcps_has_feature( (_d), PCPS_HAS_SERIAL ) @@ -1514,8 +1258,9 @@ typedef struct // We only report that XMR is supported if all required features are supported. #define _pcps_has_ri_xmr( _p_ri ) ( _pcps_has_ri_feature( (_p_ri), GPS_HAS_XMULTI_REF ) && \ _pcps_has_ri_feature( (_p_ri), GPS_HAS_XMRS_MULT_INSTC ) ) -//##++++++++++ should also check GPS_MODEL_HAS_XMR_HOLDOVER_INTV, which is a builtin featur flag only +//### TODO should also check GPS_MODEL_HAS_XMR_HOLDOVER_INTV, which is a builtin feature flag only +#endif // _USE_DEV_MACROS // There are some versions of IRIG receiver cards which ignore the TFOM code @@ -1538,28 +1283,29 @@ typedef struct // PCI bridge built into the chip. Unfortunately there are some mainboards out there // which do not handle PCI resources behind this PCI bridge correctly. The symptom is // usually that both I/O address ranges of these cards get the same base address -// assigned by the BIOS, and the efeect is that in this case a card is not accessible +// assigned by the BIOS, and the effect is that in this case a card is not accessible // properly, since both I/O ranges try to respond to the same I/O addresses. -// As a consequence data read from the card is usually garbage. +// As a consequence, data read from the card is usually garbage. // The only known fix for this is a BIOS update for the mainboard which makes the // BIOS handle the card's resources properly. // The macro below can be used to test if both port base addresses assigned to a card // are identical, and thus the BIOS is probably faulty:: #define _pcps_pci_cfg_err( _d ) \ - ( _pcps_is_pci( _d ) && ( _pcps_port_base( _d, 1 ) == _pcps_port_base( _d, 0 ) ) ) + ( _pcps_is_pci( _d ) && _pcps_short_port_base( _d, 0 ) && \ + ( _pcps_short_port_base( _d, 1 ) == _pcps_short_port_base( _d, 0 ) ) ) -// There are some versions of GPS PCI firmware which may occasionally return -// a HR time stamp which is wrong by 20 milliseconds, if the HR time is read -// right after some GPS data. As a workaround for that bug an application -// must wait at least 1.5 ms and then just read the PCPS_TIME structure +// There are some old firmware versions of GPS PCI cards which may occasionally +// return a HR time stamp which is wrong by 20 milliseconds, if the HR time is +// read right after some GPS data. As a workaround for that bug an application +// must wait at least 1.5 ms and then just read the PCPS_TIME structure // in order to re-initialize the software interface state. -// This has been fixed in more recent versions of the affected firmware, -// but this macro can be used to let an application determine whether it -// must account for this bug with a given card and firmware version. -#define _must_do_fw_workaround_20ms( _d ) \ +// This has been fixed in more recent versions of the affected firmware. +// This macro can be used to let an application determine whether it has to +// account for this bug with a given card and firmware version. +#define _pcps_fw_has_20ms_bug( _d ) \ ( \ ( _pcps_type_num( _d ) == PCPS_TYPE_GPS168PCI && _pcps_fw_rev_num( _d ) < 0x0102 ) || \ ( _pcps_type_num( _d ) == PCPS_TYPE_GPS167PCI && _pcps_fw_rev_num( _d ) < 0x0420 ) \ @@ -1568,6 +1314,22 @@ typedef struct /** + * @brief Codes used with ::IOCTL_DEV_FEAT_REQ::feat_type + */ +enum DEV_FEAT_TYPES +{ + DEV_FEAT_TYPE_BUILTIN, ///< feat_num field contains one of the ::GPS_BUILTIN_FEATURE_BITS + DEV_FEAT_TYPE_REF_TYPE, ///< feat_num field contains one of the ::PCPS_REF_TYPES + DEV_FEAT_TYPE_PCPS, ///< feat_num field contains one of the ::PCPS_FEATURE_BITS + DEV_FEAT_TYPE_RI, ///< feat_num field contains one of the ::GPS_FEATURE_BITS + DEV_FEAT_TYPE_XFEAT, ///< feat_num field contains one of the ::MBG_XFEATURE_BITS + DEV_FEAT_TYPE_TLV_FEAT, ///< feat_num field contains one of the ::MBG_TLV_FEAT_TYPES + N_DEV_FEAT_TYPES +}; + + + +/** * @brief Device driver information * * Used to pass info on the device driver to @@ -1578,6 +1340,7 @@ typedef struct uint16_t ver_num; ///< the device driver's version number uint16_t n_devs; ///< the number of devices handled by the driver PCPS_ID_STR id_str; ///< the device driver's ID string + } PCPS_DRVR_INFO; @@ -1600,6 +1363,7 @@ typedef struct { MBG_PC_CYCLES cycles; PCPS_TIME t; + } PCPS_TIME_CYCLES; @@ -1613,21 +1377,23 @@ typedef struct typedef struct { MBG_PC_CYCLES cycles; - PCPS_TIME_STAMP tstamp; /**< High resolution time stamp (UTC) */ + PCPS_TIME_STAMP tstamp; ///< High resolution time stamp (%UTC) + } PCPS_TIME_STAMP_CYCLES; #define _mbg_swab_pcps_time_stamp_cycles( _p ) \ +do \ { \ _mbg_swab_mbg_pc_cycles( &(_p)->cycles ); \ _mbg_swab_pcps_time_stamp( &(_p)->tstamp ); \ -} +} while ( 0 ) /** * @brief High resolution time plus associated system cycles count * - * Contains current high resolution UTC time from a device, including + * Contains current high resolution %UTC time from a device, including * local time offset and status, plus an associated PC cycles counter value * useful to compensate execution time. */ @@ -1635,13 +1401,15 @@ typedef struct { MBG_PC_CYCLES cycles; PCPS_HR_TIME t; + } PCPS_HR_TIME_CYCLES; #define _mbg_swab_pcps_hr_time_cycles( _p ) \ +do \ { \ _mbg_swab_mbg_pc_cycles( &(_p)->cycles ); \ _mbg_swab_pcps_hr_time( &(_p)->t ); \ -} +} while ( 0 ) @@ -1659,13 +1427,15 @@ typedef struct { PCPS_HR_TIME_CYCLES ref_hr_time_cycles; ///< HR time read from the card, plus cycles MBG_SYS_TIME_CYCLES sys_time_cycles; ///< system time stamp plus associated cycles + } MBG_TIME_INFO_HRT; #define _mbg_swab_mbg_time_info_hrt( _p ) \ +do \ { \ _mbg_swab_pcps_hr_time_cycles( &(_p)->ref_hr_time_cycles ); \ _mbg_swab_mbg_sys_time_cycles( &(_p)->sys_time_cycles ); \ -} +} while ( 0 ) @@ -1678,22 +1448,31 @@ typedef struct * into account the latencies determined from the cycles counts. * * Since the card's time stamp is taken from the fast memory mapped registers - * this structure does *not* contain the card's status information (e.g. sync status). + * this structure does ***not*** contain the card's status information (e.g. sync status). */ typedef struct { PCPS_TIME_STAMP_CYCLES ref_tstamp_cycles; ///< HR timestamp from the card, plus cycles MBG_SYS_TIME_CYCLES sys_time_cycles; ///< system timestamp plus associated cycles + } MBG_TIME_INFO_TSTAMP; #define _mbg_swab_mbg_time_info_tstamp( _p ) \ +do \ { \ _mbg_swab_pcps_time_stamp_cycles( &(_p)->ref_tstamp_cycles ); \ _mbg_swab_mbg_sys_time_cycles( &(_p)->sys_time_cycles ); \ -} +} while ( 0 ) +/** + * @defgroup group_irq_stat_info IRQ status information + * + * @anchor PCPS_IRQ_STAT_INFO_DEFS + * + * @{ */ + typedef uint32_t PCPS_IRQ_STAT_INFO; // Flags used with PCPS_IRQ_STAT_INFO: @@ -1703,112 +1482,64 @@ typedef uint32_t PCPS_IRQ_STAT_INFO; #define PCPS_IRQ_STATE_DANGER ( PCPS_IRQ_STAT_ENABLED | PCPS_IRQ_STAT_UNSAFE ) +/** @} defgroup group_irq_stat_info */ + + + +#define PCPS_FW_STR_FMT "%X.%02X" + #define _pcps_fw_rev_num_major( _v ) \ - ( ( (_v) >> 8 ) & 0xFF ) + ( (_v) >> 8 ) #define _pcps_fw_rev_num_minor( _v ) \ ( (_v) & 0xFF ) + #if defined( _USING_BYTE_ALIGNMENT ) #pragma pack() // set default alignment #undef _USING_BYTE_ALIGNMENT #endif -// We must use native alignment here! +#if !defined( MBG_TGT_KERNEL ) -// The structure below is used by the IOCTL_PCPS_GENERIC_... calls. +static __mbg_inline +void setup_hr_time_cycles_from_timestamp_cycles( PCPS_HR_TIME_CYCLES *p_ht_c, + const PCPS_TIME_STAMP_CYCLES *p_ts_c ) +{ + memset( p_ht_c, 0, sizeof( *p_ht_c ) ); -#if defined( MBG_TGT_LINUX ) - #if defined( MBG_ARCH_ARM ) || defined( MBG_ARCH_SPARC ) - #define USE_IOCTL_GENERIC_REQ 0 - #endif -#endif + p_ht_c->t.tstamp = p_ts_c->tstamp; + p_ht_c->cycles = p_ts_c->cycles; -#if defined( MBG_TGT_WIN32 ) - // required for 32bit/64 bit compatibility - #define USE_IOCTL_GENERIC_REQ 0 -#endif +} // setup_hr_time_cycles_from_timestamp_cycles -#if !defined( USE_IOCTL_GENERIC_REQ ) - #define USE_IOCTL_GENERIC_REQ 1 #endif -#if USE_IOCTL_GENERIC_REQ - -/** - * @brief A structure used to pass generic IOCTL requests to the kernel driver - * - * @note This does not work properly under Linux/Sparc where the kernel - * may be 64 bit while user space is 32 bit, which leads to different sizes - * for pointers and size_t. - */ -typedef struct -{ - ulong info; - const void *in_p; - size_t in_sz; - void *out_p; - size_t out_sz; - -} IOCTL_GENERIC_REQ; - -#define _MBG_IOG( _t, _n, _s ) _MBG_IOW( _t, _n, _s ) - -#else /** - * @brief Control structure used for generic IOCTL requests + * @brief A string buffer for a unique device ID * - * Used by the IOCTL_PCPS_GENERIC_... calls. + * The unique ID is made up of the device model name + * and its serial number, i.e. [model_name]_[serial_number] + * E.g.: "GPS170PCI_028210040670" * - * @note Is slower, but avoids OS-specific problems occurring - * with IOCTL_GENERIC_REQ. + * @see ::snprint_dev_name + * @see ::MBG_DEV_NAME_FMT */ -typedef struct -{ - uint32_t info; - uint32_t data_size_in; - uint32_t data_size_out; -} IOCTL_GENERIC_CTL; +typedef char MBG_DEV_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1]; + /** - * @brief Data buffer used for generic IOCTL requests - * - * Used by the IOCTL_PCPS_GENERIC_... calls. + * @brief A string format specifier for ::MBG_DEV_NAME * - * @note Is slower, but avoids OS-specific problems occurring - * with IOCTL_GENERIC_REQ. + * @see ::snprint_dev_name + * @see ::MBG_DEV_NAME_FMT */ -typedef struct -{ - IOCTL_GENERIC_CTL ctl; - uint8_t data[1]; -} IOCTL_GENERIC_BUFFER; - -#define _MBG_IOG( _t, _n, _s ) _MBG_IO( _t, _n ) - -#endif - - - -#if !defined( MBG_TGT_KERNEL ) - -static __mbg_inline -void setup_hr_time_cycles_from_timestamp_cycles( PCPS_HR_TIME_CYCLES *p_ht_c, - const PCPS_TIME_STAMP_CYCLES *p_ts_c ) -{ - memset( p_ht_c, 0, sizeof( *p_ht_c ) ); - - p_ht_c->t.tstamp = p_ts_c->tstamp; - p_ht_c->cycles = p_ts_c->cycles; - -} // setup_hr_time_cycles_from_timestamp_cycles - -#endif +#define MBG_DEV_NAME_FMT "%s_%s" /* End of header body */ diff --git a/c/mbglib/include/pcpsiobf.h b/c/mbglib/include/pcpsiobf.h new file mode 100644 index 0000000..ab45c27 --- /dev/null +++ b/c/mbglib/include/pcpsiobf.h @@ -0,0 +1,169 @@ + +/************************************************************************** + * + * $Id: pcpsiobf.h 1.3 2019/04/03 12:33:22Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions an I/O buffer that can be used in kernel space + * and user space, on targets that support IOCTL as well as + * on targets that don't. + * + * ----------------------------------------------------------------------- + * $Log: pcpsiobf.h $ + * Revision 1.3 2019/04/03 12:33:22Z martin + * Excluded some PCPS_IO_BUFFER fields that are currently not required. + * Revision 1.2 2018/01/18 14:52:52 martin + * Fix for C++ builds. + * Revision 1.1 2018/01/15 10:31:26Z martin + * Initial revision with structures moved from mbgioctl.h here. + * + **************************************************************************/ + +#ifndef _PCPSIOBF_H +#define _PCPSIOBF_H + +#include <pcpsdev.h> +#include <cfg_hlp.h> +#include <mbggeo.h> + + +/* Start of header body */ + +// We must *not* use byte-alignment here. + + +#ifdef __cplusplus +extern "C" { +#endif + + +/** + * @brief A wrapper struct for the ::LLA array type + * + * Simplifies usage of macros which expect ponters to structures + * rather than the address of an array. + * + * @see ::LLA + */ +typedef struct +{ + LLA lla; +} LLAs; + + + +/** + * @brief A wrapper struct for the ::XYZ array type. + * + * Simplifies usage of macros which expect ponters to structures + * rather than the address of an array. + * + * @see ::XYZ + */ +typedef struct +{ + XYZ xyz; +} XYZs; + + + +/** + * @brief An I/O buffer for bus level devices + * + * Can be used in kernel space and user space, on targets that + * support IOCTL calls as well as on targets that don't. + */ +typedef union +{ + PCPS_STATUS_PORT pcps_status_port_usb; // only used with USB devices + PCPS_ID_STR fw_id; + PCPS_SN_STR sernum; + PCPS_TIME pcps_time; + PCPS_STIME pcps_stime; + PCPS_HR_TIME pcps_hr_time; + PCPS_TIME_STAMP pcps_time_stamp; + PCPS_SERIAL pcps_serial; + PCPS_TZCODE pcps_tzcode; + PCPS_TZDL pcps_tzdl; + MBG_REF_OFFS mbg_ref_offs; + MBG_OPT_INFO mbg_opt_info; + MBG_OPT_SETTINGS mbg_opt_settings; + IRIG_INFO irig_info; + IRIG_SETTINGS irig_settings; + PCPS_UCAP_ENTRIES pcps_ucap_entries; + TZDL tzdl; + SW_REV sw_rev; + BVAR_STAT bvar_stat; + TTM ttm; + PORT_PARM port_parm; + ANT_INFO ant_info; + ENABLE_FLAGS enable_flags; + STAT_INFO stat_info; + RECEIVER_INFO receiver_info; + GPS_CMD gps_cmd; + IDENT ident; + POS pos; + XYZs xyzs; + LLAs llas; + ANT_CABLE_LEN ant_cable_len; + PORT_SETTINGS_IDX port_settings_idx; + SYNTH synth; + SYNTH_STATE synth_state; + ALL_POUT_INFO_IDX all_pout_info_idx; + POUT_SETTINGS_IDX pout_settings_idx; + ALL_STR_TYPE_INFO_IDX all_str_type_info_idx; + ALL_PORT_INFO_IDX all_port_info_idx; + ALL_PTP_UC_MASTER_INFO_IDX all_ptp_uc_master_info_idx; + MBG_TIME_SCALE_INFO mbg_time_scale_info; + MBG_TIME_SCALE_SETTINGS mbg_time_scale_settings; + UTC utc; + MBG_IRIG_CTRL_BITS mbg_irig_ctrl_bits; + LAN_IF_INFO lan_if_info; + IP4_SETTINGS ip4_settings; + PTP_STATE ptp_state; + PTP_CFG_INFO ptp_cfg_info; + PTP_CFG_SETTINGS ptp_cfg_settings; + PCPS_IRIG_TIME pcps_irig_time; + MBG_RAW_IRIG_DATA mbg_raw_irig_data; + PTP_UC_MASTER_CFG_LIMITS ptp_uc_master_cfg_limits; + PTP_UC_MASTER_SETTINGS_IDX ptp_uc_master_settings_idx; + PCPS_TIME_CYCLES pcps_time_cycles; + PCPS_HR_TIME_CYCLES pcps_hr_time_cycles; + MBG_DBG_PORT mbg_dbg_port; + // MBG_DBG_DATA mbg_dbg_data; // currently not required + // MBG_PC_CYCLES_FREQUENCY mbg_pc_cycles_frequency; // currently not required + MBG_TIME_INFO_HRT mbg_time_info_hrt; + // MBG_TIME_INFO_TSTAMP mbg_time_info_tstamp; // currently not required + CORR_INFO corr_info; + TR_DISTANCE tr_distance; + MBG_DEBUG_STATUS debug_status; + MBG_NUM_EVT_LOG_ENTRIES num_evt_log_entries; + MBG_EVT_LOG_ENTRY evt_log_entry; + MBG_GNSS_MODE_SETTINGS gnss_mode_settings; + MBG_GNSS_MODE_INFO gnss_mode_info; + ALL_GNSS_SAT_INFO_IDX all_gnss_sat_info_idx; + MBG_GPIO_CFG_LIMITS mbg_gpio_cfg_limits; + ALL_GPIO_INFO_IDX all_gpio_info_idx; + ALL_GPIO_STATUS_IDX all_gpio_status_idx; + MBG_GPIO_SETTINGS_IDX mbg_gpio_settings_idx; + XMULTI_REF_INSTANCES xmulti_ref_instances; + ALL_XMULTI_REF_STATUS_IDX all_xmulti_ref_status_idx; + ALL_XMULTI_REF_INFO_IDX all_xmulti_ref_info_idx; + XMULTI_REF_SETTINGS_IDX xmulti_ref_settings_idx; + XMR_HOLDOVER_STATUS xmr_holdover_status; + +} PCPS_IO_BUFFER; + + +#ifdef __cplusplus +} +#endif + + +/* End of header body */ + +#undef _ext + +#endif /* _PCPSIOBF_H */ diff --git a/c/mbglib/include/rs232.h b/c/mbglib/include/rs232.h deleted file mode 100644 index 8c8e19e..0000000 --- a/c/mbglib/include/rs232.h +++ /dev/null @@ -1,135 +0,0 @@ - -/************************************************************************** - * - * $Id: rs232.h 1.12 2012/01/12 14:46:06Z martin REL_M $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for template.c. - * - * ----------------------------------------------------------------------- - * $Log: rs232.h $ - * Revision 1.12 2012/01/12 14:46:06Z martin - * Removed German umlauts in old RCS log entries. - * Revision 1.11 2006/11/01 15:42:38Z martin - * Picked up Andre's new method SetComParameter(). - * Revision 1.10 2006/10/30 14:47:51Z martin - * Updated function prototypes. - * Revision 1.9 2004/04/14 08:39:46Z martin - * Pack structures 1 byte aligned. - * Revision 1.8 2003/10/21 08:24:29Z martin - * Changed "bool" to "BOOL" to avoid compiler warnings. - * Revision 1.7 2003/10/16 12:44:36Z martin - * Don't define class if compiled without _cplusplus. - * Revision 1.6 2003/03/27 16:11:17 Daniel - * removed obsolete header files - * Revision 1.5 2003/03/10 09:26:02Z Daniel - * increased buffer size for ComName - * Revision 1.4 2002/11/26 10:24:22Z martin - * Port handle made public. - * New variables which keep transmission times per - * bit and per char in 100 nsec units, and bits per char. - * Use standard file template. - * Revision 1.3 2001/09/12 09:50:12Z Udo - * Fehler korrigiert: - * Schutz gegen rekursiven Include - * undef _ext ergaenzt - * Revision 1.2 2001/02/14 11:19:58Z WERNER - * Clear_Error Funktion zugefuegt - * Revision 1.1 2000/08/29 07:47:38Z WERNER - * Initial revision - * - **************************************************************************/ - -#ifndef _RS232_H -#define _RS232_H - - -/* Other headers to be included */ - -#include <use_pack.h> - -#include <windows.h> - - -#ifdef _RS232 - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if defined( _USE_PACK ) // set byte alignment - #pragma pack( 1 ) -#endif - - -typedef struct -{ - char ComName[7]; - char Framing[4]; - long Baudrate; -} COMSTRUCT; - - -#ifdef __cplusplus - -class Comport{ -public: - HANDLE Handle; - ULONG bits_per_char; // mostly 10 or 11, depending on the framing - ULONG bit_time; // 100 nsec units required to transmit 1 bit and 1 char, - ULONG char_time; // depending on transmission speed and bits per char. - - class InitException { }; - Comport( COMSTRUCT *Cpnt ); // Konstruktor - ~Comport(void); // Destruktor - - void SetComParameter( COMSTRUCT *Cpnt ); - int Read( LPSTR lpszBlock, int nMaxLength ); - int Write( LPSTR lpszBlock, int nMaxLength ); - BOOL RxClear( void ); - BOOL TxClear( void ); - DWORD ClearError( void ); -}; - -#endif - -/* function prototypes: */ - -#ifdef __cplusplus -extern "C" { -#endif - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - HANDLE mbg_open_serial( const char *device_name ) ; - void mbg_log_com_error( DWORD dwErrorFlags, COMSTAT *pComStat ) ; - DWORD mbg_clear_comm_error( HANDLE h ) ; - int mbg_setup_port_list( int max_port_num, void (*callbackfnc)( const char *dev_name ) ) ; - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - - -#if defined( _USE_PACK ) // set default alignment - #pragma pack() -#endif - -/* End of header body */ - -#undef _ext -#undef _DO_INIT - -#endif /* _RS232_H */ - diff --git a/c/mbglib/include/shmem.h b/c/mbglib/include/shmem.h deleted file mode 100644 index f59d354..0000000 --- a/c/mbglib/include/shmem.h +++ /dev/null @@ -1,253 +0,0 @@ - -/************************************************************************** - * - * $Id: shmem.h 1.20.1.1 2010/09/16 14:01:12Z martin TRASH $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and Prototypes for shmem.cpp. - * Shared Memory Block - * - * ----------------------------------------------------------------------- - * $Log: shmem.h $ - * Revision 1.20.1.1 2010/09/16 14:01:12Z martin - * Branch used to test handle leak under Win Server 2008. - * Revision 1.20 2010/06/25 13:49:22Z daniel - * Updated function prototypes. - * Revision 1.19 2009/08/14 09:18:39Z daniel - * Added new enum and parameter in SH_MEM_STATUS - * structure to send warnings to the monitor program. - * Revision 1.18 2009/03/16 16:50:36Z martin - * #include myutil.h to avoid build errors. - * Revision 1.17 2009/01/12 13:51:19Z daniel - * Added error code MBG_SVC_ERR_REF_TIME_STEP. - * Prepared support for the export of high resolution systemtime. - * Added structure SH_MEM_SYSTIME. - * Updated function prototypes. - * Revision 1.16 2006/05/23 19:31:06Z martin - * Split shared mem into 2 different struct, one which is written, and - * one which is read only by the service. - * Introduced ShMemStatus::err_info to indicate errors. - * Revision 1.15 2006/05/02 10:34:13Z martin - * Cleaned up and re-organized shared memory structure. - * Moved some definitions to timecnv.h. - * Revision 1.14 2005/06/09 10:35:53Z martin - * Moved declarations of serclock_cfg and adjtm_cfg here. - * Revision 1.13 2004/04/23 09:44:04Z martin - * Pack structures 1 byte aligned. - * Renamed shared memory fields. - * Made fmt string local to module. - * Updated function prototypes. - * Revision 1.12 2004/02/12 10:23:33Z martin - * Updated function prototypes. - * Revision 1.11 2003/12/05 08:57:33Z martin - * Made some variables local. - * Removed some obsolete variables. - * Revision 1.10 2003/10/29 08:18:00Z martin - * Removed obsolete fields. - * Revision 1.9 2003/09/10 09:14:47Z Daniel - * Deleted structure members that were added in mbgsvctl. - * Revision 1.8 2003/03/31 16:20:47 martin - * Made vars extern "C" to fix linker errors under MSVC++. - * Revision 1.7 2002/10/01 07:48:29Z Udo - * New members for Sharedmem: CurrState[], clock_type, and tray_icon_started - * used by the Tray-Icon program - * Revision 1.6 2002/09/26 09:49:02Z martin - * Use standard file structure. - * Include windows.h for basic data types. - * Revision 1.5 2002/08/29 09:20:04Z Daniel - * "check_tz" removed - * "mode" added - * - **************************************************************************/ - -#ifndef _SHMEM_H -#define _SHMEM_H - -/* Other headers to be included */ - -// #include <mbgsvctl.h> -#include <timecnv.h> -// #include <myutil.h> -#include <use_pack.h> - -#if defined( MBG_TGT_WIN32 ) - #include <messages.h> - #include <windows.h> -#endif - - -#ifdef _SHMEM - #define _ext -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if defined( _USE_PACK ) // set byte alignment - #pragma pack( 1 ) -#endif - - -#ifdef __cplusplus -extern "C" { -#endif - - -typedef struct -{ - DWORD port_number; - DWORD baudrate_index; - DWORD frame_type; - DWORD telegram_type; - DWORD mode; - DWORD error; -} SERIAL_PORT_PARM; - - -typedef struct -{ - DWORD code; - REF_TIME time; -} ERR_INFO; - -// codes used with ERR_INFO::code: -enum -{ - MBG_SVC_NO_ERROR, - MBG_SVC_ERR_OPEN_CLOCK_DEV, - MBG_SVC_ERR_OPEN_SERIAL_PORT, - MBG_SVC_ERR_SAME_REF_TIME, - MBG_SVC_ERR_REF_TIME_STEP, - N_MBG_SVC_ERR_CODE -}; - - - -/** - The enum and bitmasks used below are or'ed with - the "warnings" value of SH_MEM_STATUS -*/ -enum -{ - MBG_SVC_WARNING_SYS_TIME_ADJ, - N_MBG_SVC_WARNINGS -}; - - -#define MSK_SVC_WARNING_SYS_TIME_ADJ ( 1UL << MBG_SVC_WARNING_SYS_TIME_ADJ ) - - - -typedef struct -{ - DWORD mbgadjtm_version; - REF_TIME sys_time; - REF_TIME ref_time; - REF_TIME last_serial_sync_time; - REF_TIME last_set_time; - DWORD last_set_time_diff; - DWORD last_dyn_correction; - DWORD diff; - DWORD warnings; - ERR_INFO err_info; -} SH_MEM_STATUS; - - -// The code below is used with SH_MEM_STATUS::last_dyn_correction -// in order to indicate that the service is waiting for the clock -// ty synchronize: -#define SHM_LAST_DYN_WAIT_SYNC 0xFFFF - - -typedef struct -{ - DWORD parameters_changed; // read by the service -} SH_MEM_CMD; - - -typedef struct -{ - ULONGLONG LastTimerCount; - ULONGLONG LastTimerTime; -} SH_MEM_SYSTIME; - - - -_ext SH_MEM_STATUS ShMemStatus; -_ext SH_MEM_CMD ShMemCmd; -_ext SH_MEM_SYSTIME ShMemSysTime; - - -#define _clr_err_info() \ - _memclr( &ShMemStatus.err_info ); - - -// clear error only if error code matches -#define _clr_err_info_code( _code ) \ -{ \ - if ( ShMemStatus.err_info.code == ( _code ) ) \ - _clr_err_info(); \ -} - - -#define _set_err_info_code_time( _code, _t ) \ -{ \ - _clr_err_info(); \ - ShMemStatus.err_info.code = _code; \ - ShMemStatus.err_info.time = _t; \ -} - - -#define _set_err_info_code( _code ) \ -{ \ - _clr_err_info(); \ - ShMemStatus.err_info.code = _code; \ -} - -#define _set_warning_bit( _bit ) \ -{ \ - ShMemStatus.warnings |= _bit; \ -} - - -#define _clr_warning_bit( _bit ) \ -{ \ - ShMemStatus.warnings &= ~_bit; \ -} - - - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - int ReadShMemStatus( void ) ; - int WriteShMemStatus( void ) ; - int ReadShMemCmd( void ) ; - int WriteShMemCmd( void ) ; - int ReadShMemSysTime( void ) ; - int WriteShMemSysTime( void ) ; - int CreateShMem( void ) ; - -/* ----- function prototypes end ----- */ - -#ifdef __cplusplus -} -#endif - - -#if defined( _USE_PACK ) // set default alignment - #pragma pack() -#endif - -/* End of header body */ - -#undef _ext - -#endif /* _SHMEM_H */ - diff --git a/c/mbglib/include/timecnv.h b/c/mbglib/include/timecnv.h deleted file mode 100644 index 767386e..0000000 --- a/c/mbglib/include/timecnv.h +++ /dev/null @@ -1,362 +0,0 @@ - -/************************************************************************** - * - * $Id: timecnv.h 1.13.1.15 2011/11/07 17:38:23Z martin TRASH $ - * - * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany - * - * Description: - * Definitions and prototypes for timecnv.c. - * - * ----------------------------------------------------------------------- - * $Log: timecnv.h $ - * Revision 1.13.1.15 2011/11/07 17:38:23Z martin - * Revision 1.13.1.14 2011/09/23 14:03:28Z martin - * Revision 1.13.1.13 2011/09/23 13:57:02Z martin - * Moved temp. code elsewhere. - * Revision 1.13.1.12 2011/09/14 14:17:56 martin - * Revision 1.13.1.11 2011/09/14 14:13:09Z martin - * Temporarily moved definition of MBGADJTM_CFG and related stuff here. - * Revision 1.13.1.10 2011/08/25 15:11:30Z marvin - * Changed lenght of COMSTRUCT::ComName from 7 to 20 chars for Unix only. - * Revision 1.13.1.9 2011/08/18 13:53:39 martin - * Revision 1.13.1.8 2011/08/18 12:50:01Z martin - * Temporarily moved definition of MBG_SERCLOCK_CFG and related stuff here. - * No need to include mbgsvctl.h anymore. - * Revision 1.13.1.7 2011/07/19 15:53:13Z martin - * Revision 1.13.1.6 2011/07/05 08:36:39Z martin - * Cleaned up handling of pragma pack(). - * Revision 1.13.1.5 2010/11/08 12:25:17 martin - * Fixed Windows build. - * Revision 1.13.1.4 2010/03/05 10:00:25Z martin - * Moved FILETIME_1970, HNS_PER_SEC and HNS_PER_MS to mbgtime.h - * Revision 1.13.1.3 2010/03/05 09:38:59 martin - * Commented out some specific windows structs and functions. - * The constants of this file can be used on unix systems now. - * Revision 1.13.1.2 2010/01/08 15:05:11 martin - * Revision 1.13.1.1 2010/01/07 16:24:31Z martin - * Revision 1.13 2009/03/17 09:27:08Z daniel - * Updated function prototypes. - * Revision 1.12 2009/01/12 13:57:36Z daniel - * Uses ULL instead of LLU. - * FILETIME_1970 with 64 bit suffix is different for GnuC and VC. - * Added perf_count_on_time in SERIAL_TIME_STRING. - * Revision 1.11 2006/05/04 14:13:38Z martin - * Added initializers for time string format names. - * Added macro _secs_to_hns(). - * Revision 1.10 2006/05/02 10:39:09Z martin - * Moved some definitions here and renamed some symbols. - * Added new definitions for unified parsing of time strings. - * Cleanup and renamed field in SERIAL_TIME_STRING. - * Updated function prototypes. - * Revision 1.9 2005/11/15 14:36:33Z martin - * Use new type PCPS_TIME_STATUS_X in REF_TIME. - * Updated function prototypes. - * Revision 1.8 2005/06/09 10:35:18Z martin - * Moved declaration of serclock_cfg elsewhere. - * Revision 1.7 2004/04/27 07:41:47Z martin - * Moved some macros here. - * Moved some constants from other files here. - * Pack structures 1 byte aligned. - * Updated function prototypes. - * Revision 1.6 2004/02/12 10:16:21Z martin - * Updated function prototypes. - * Revision 1.5 2004/01/06 16:26:56Z martin - * Updated function prototypes. - * Revision 1.4 2003/12/19 16:13:10Z martin - * New parameter for GET_REF_TIME_FNC type. - * Revision 1.3 2003/09/12 12:47:41Z Daniel - * added include file mbgsvctl.h - * Revision 1.2 2002/09/30 12:17:12 martin - * Added structure SERIAL_TIME_STRING. - * Added type of function to get REF_TIME. - * Updated function prototypes. - * Revision 1.1 2002/08/28 10:47:36Z Daniel - * Initial revision - * - **************************************************************************/ - -#ifndef _TIMECNV_H -#define _TIMECNV_H - -/* Other headers to be included */ - -#include <mbg_tgt.h> -#include <gpsdefs.h> -#include <pcpsdefs.h> -#include <pcpsutil.h> -#include <mbgtime.h> -#include <mbgpccyc.h> - -#if defined( MBG_TGT_WIN32 ) - #include <rs232.h> - #include <mbgdevio.h> - #include <mbg_serclock_cfg.h> -#endif //MBG_TGT_WIN32 - -#include <use_pack.h> - - -#ifdef _TIMECNV - #define _ext - #define _DO_INIT -#else - #define _ext extern -#endif - - -/* Start of header body */ - -#if defined( _USE_PACK ) - #pragma pack( 1 ) // set byte alignment - #define _USING_BYTE_ALIGNMENT -#endif - - -#ifdef __cplusplus -extern "C" { -#endif - -// ASCII definitions - -#define ASCII_STX 0x02 -#define ASCII_ETX 0x03 -#define ASCII_BEL 0x07 -#define ASCII_BS 0x08 -#define ASCII_LF 0x0A -#define ASCII_CR 0x0D -#define ASCII_XON 0x11 -#define ASCII_XOFF 0x13 - -#define STR_STX "\x2" -#define STR_ETX "\x3" - - -#define _perf_cnt_to_us( _v ) \ - ( (double) (_v) * (double) ( HNS_PER_SEC / 10 ) / (double) PerfFrequency ) - -#define _perf_cnt_to_hns( _v ) \ - ( (double) (_v) * (double) HNS_PER_SEC / (double) PerfFrequency ) - -#define _secs_to_hns( _v ) \ - ( ( (LONGLONG) (_v) ) * HNS_PER_SEC ) - -#if defined( MBG_TGT_WIN32 ) -// ATTENTION: the declaration below may be tricky. Even though -// no problems have been observed, yet, the MS docs clearly say -// there may be alignment problems under 64 bit Windows. -// If the FILETIME members are not 32 bit aligned then accessing -// the dwl member below will yield wrong values. -typedef union -{ - FILETIME ft; - uint64_t dwl; -} FT_DWL; - - - -typedef struct -{ - FT_DWL ftdwl; // based on UTC - int32_t utc_offs; // [sec] - PCPS_TIME_STATUS_X status; // extended status -} REF_TIME; - - - -typedef struct -{ - REF_TIME rt; - MBG_PC_CYCLES cycles; -} REF_TIME_CYCLES; - - - -#define MAX_TIMESTR_LEN 150 - -typedef struct -{ - char timestring[MAX_TIMESTR_LEN]; - REF_TIME sys_time_on_time; - MBG_PC_CYCLES sys_cycles_on_time; -} SERIAL_TIME_STRING; - - -// a pointer to a function that takes a time stamp of the system time -typedef int (*GET_REF_TIME_FNC)( REF_TIME *tp, LARGE_INTEGER *pli ); - -#endif //MBG_TGT_WIN32 - -// supported time string formats - -enum -{ - SF_MBG_STD, - SF_SAT, - SF_INTERFLEX, - N_SF -}; - - -// Initializers for the time string format names - -#define SF_NAME_MBG_STD_ENG "Meinberg Time String" -#define SF_NAME_MBG_STD_GER "Meinberg Zeittelegramm" - -#define SF_NAME_SAT_ENG "SAT Time String" -#define SF_NAME_SAT_GER "SAT Zeittelegramm" - -#define SF_NAME_INTERFLEX_ENG "Interflex Time String" -#define SF_NAME_INTERFLEX_GER "Interflex Zeittelegramm" - - -#define SF_NAMES_ENG \ -{ \ - SF_NAME_MBG_STD_ENG, \ - SF_NAME_SAT_ENG, \ - SF_NAME_INTERFLEX_ENG \ -} - - -#define SF_NAMES_LSTR \ -{ \ - { SF_NAME_MBG_STD_ENG, SF_NAME_MBG_STD_GER }, \ - { SF_NAME_SAT_ENG, SF_NAME_SAT_GER }, \ - { SF_NAME_INTERFLEX_ENG, SF_NAME_INTERFLEX_GER } \ -} - - - -// a structure to store the characteristics of a time string - -typedef struct -{ - const char *chk_fmt; // to check the format, len must be str len - char skip_char; - char first_char; - char on_time_char; -} TS_SPEC; - - -#define TS_SPEC_MBG_STD \ -{ \ - STR_STX "D:__.__.__;T:_;U:__.__.__;____" STR_ETX, \ - '_', \ - ASCII_STX, \ - ASCII_STX \ -} - -#define TS_SPEC_SAT \ -{ \ - STR_STX "__.__.__/_/__:__:__________" STR_ETX, \ - '_', \ - ASCII_STX, \ - ASCII_STX \ -} - -#define TS_SPEC_INTERFLEX \ -{ \ - STR_STX "IFD:__.__.__;T:_;U:__.__.__;____" STR_ETX, \ - '_', \ - ASCII_STX, \ - ASCII_STX \ -} - - -// Default initializer for an array of N_SF TS_SPECs - -#define DEFAULT_TS_SPECS \ -{ \ - TS_SPEC_MBG_STD, \ - TS_SPEC_SAT, \ - TS_SPEC_INTERFLEX \ -} - -#if defined( MBG_TGT_WIN32 ) - -_ext TS_SPEC ts_spec[N_SF] -#ifdef _DO_INIT - = DEFAULT_TS_SPECS -#endif -; - - -_ext ushort year_limit -#ifdef _DO_INIT - = 1990 -#endif -; - -#endif //MBG_TGT_WIN32 - - - -#if defined( MBG_TGT_WIN32 ) - -static __mbg_inline -void mbg_pcps_time_stamp_to_filetime( FILETIME *p_ft, const PCPS_TIME_STAMP *p_ts ) -{ - uint64_t ts64; - uint32_t frac; - - frac = frac_sec_from_bin( p_ts->frac, PCPS_HRT_FRAC_SCALE ); - ts64 = ( (uint64_t) p_ts->sec ) * HNS_PER_SEC + FILETIME_1970 + frac; - - p_ft->dwHighDateTime = (uint32_t) ( ts64 >> 32 ); - p_ft->dwLowDateTime = (uint32_t) ( ts64 & 0xFFFFFFFFUL ); - -} // mbg_pcps_time_stamp_to_filetime - - - -static __mbg_inline -void mbg_pcps_tstamp64_to_filetime( FILETIME *p_ft, const uint64_t *p_ts64 ) -{ - PCPS_TIME_STAMP ts; - - uint64_to_pcps_time_stamp( &ts, *p_ts64 ); - mbg_pcps_time_stamp_to_filetime( p_ft, &ts ); - -} // mbg_pcps_tstamp64_to_filetime - - - -/* function prototypes: */ - -/* ----- function prototypes begin ----- */ - -/* This section was generated automatically */ -/* by MAKEHDR, do not remove the comments. */ - - int check_time_string( const char *ts, int len, int sf ) ; - void decode_str_date_std( SYSTEMTIME *pt, const char *s ) ; - void decode_str_wday_std( SYSTEMTIME *pt, const char *s ) ; - void decode_str_time_std( SYSTEMTIME *pt, const char *s ) ; - int decode_time_str( SYSTEMTIME *pt, long *utc_offs_sec, PCPS_TIME_STATUS_X *status, const char *ts, const MBG_SERCLOCK_CFG *pcfg ) ; - void timestring_to_ref_and_sys_filetime( SERIAL_TIME_STRING *sts, REF_TIME *st, REF_TIME *rt, const MBG_SERCLOCK_CFG *pcfg ) ; - void systemtime_to_pcps_time( PCPS_TIME *pt, const SYSTEMTIME *pst ) ; - void pcps_time_to_systemtime( SYSTEMTIME *pst, const PCPS_TIME *pt ) ; - int pcps_time_to_ref_time( REF_TIME *rt, const PCPS_TIME *pt ) ; - void pcps_hr_time_to_ref_time( REF_TIME *rt, const PCPS_HR_TIME *hr_time ) ; - void pcps_hr_time_to_pcps_time( PCPS_TIME *ptime, const PCPS_HR_TIME *hr_time ) ; - -/* ----- function prototypes end ----- */ - -#endif //MBG_TGT_WIN32 - -#ifdef __cplusplus -} -#endif - - -#if defined( _USING_BYTE_ALIGNMENT ) - #pragma pack() // set default alignment - #undef _USING_BYTE_ALIGNMENT -#endif - -/* End of header body */ - -#undef _ext -#undef _DO_INIT - -#endif /* _TIMECNV_H */ diff --git a/c/mbglib/include/timeutil.h b/c/mbglib/include/timeutil.h new file mode 100644 index 0000000..39f1cf1 --- /dev/null +++ b/c/mbglib/include/timeutil.h @@ -0,0 +1,516 @@ + +/************************************************************************** + * + * $Id: timeutil.h 1.14 2019/09/27 15:26:27Z martin REL_M $ + * + * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany + * + * Description: + * Definitions and prototypes for timeutil.c + * + * ----------------------------------------------------------------------- + * $Log: timeutil.h $ + * Revision 1.14 2019/09/27 15:26:27Z martin + * New inline functions mbg_exp_time_t_to_time64_t() and + * mbg_trnc_time64_t_to_time_t(). + * Updated function prototypes and doxygen comments. + * Revision 1.13 2019/09/10 13:10:25 martin + * Fixed doxygen comments. + * Revision 1.12 2019/08/07 09:05:44 martin + * New inline function mbg_gmtime64(). + * Updated doxygen comments. + * Revision 1.11 2019/07/19 14:29:07 martin + * Define CLOCK_MONOTONIC, clock_gettime() and + * clock_settime() on Windows, if appropriate. + * Updated function prototypes. + * Revision 1.10 2019/02/11 09:49:46 martin + * Support the mingw build environment. + * Fixed build for targets that don't support 64 bit types. + * Revision 1.9 2018/12/11 15:36:40 martin + * cvt_to_time_t() now expects an int64_t type parameter. + * Revision 1.8 2018/11/29 15:32:04Z martin + * Moved some inline functions here. + * Include mbgtime.h. + * Revision 1.7 2018/01/30 09:54:12Z martin + * Updated function prototypes. + * Revision 1.6 2018/01/15 18:31:21Z martin + * Updated function prototypes. + * Revision 1.5 2017/11/16 13:34:09 philipp + * Extended ISO printing helper functions + * Revision 1.4 2017/11/16 11:33:28 philipp + * Added functions to print a time_t to ISO format + * Revision 1.3 2017/07/05 07:15:00 martin + * Provide basic support for clock_gettime()/clock_settime() + * compatible functions for Windows. + * Updated function prototypes. + * Revision 1.1 2016/07/15 14:14:20Z martin + * Initial revision + * + **************************************************************************/ + +#ifndef _TIMEUTIL_H +#define _TIMEUTIL_H + +/* Other headers to be included */ + +#include <gpsdefs.h> +#include <mbgerror.h> +#include <mbgtime.h> + +#include <time.h> +#include <stddef.h> +#include <assert.h> + + +#ifdef _TIMEUTIL + #define _ext + #define _DO_INIT +#else + #define _ext extern +#endif + + +/* Start of header body */ + +#ifdef __cplusplus +extern "C" { +#endif + + +// exclude for MinGW +#if defined( MBG_TGT_WIN32 ) || defined( MBG_TGT_DOS ) + #if !defined( MBG_TGT_MINGW ) + typedef int clockid_t; + #define clockid_t clockid_t + + #define CLOCK_REALTIME ( (clockid_t) 0 ) + #define CLOCK_MONOTONIC ( (clockid_t) 1 ) + + #define clock_gettime mbg_clock_gettime + #define clock_settime mbg_clock_settime + #endif +#endif + + + +#if defined( MBG_TGT_WIN32 ) + +#define __const__ const + +/** + * @brief A pointer to a function returning the system time as @a FILETIME. + * + * This can be e.g. the standard Windows API call @a GetSystemTimeAsFileTime + * or the @a GetSystemTimeAsPreciseFileTime API call available on Windows 8 + * and later Windows versions. + */ +typedef VOID (WINAPI *GSTAFT_FNC)(LPFILETIME lpSystemTimeAsFileTime); + +_ext GSTAFT_FNC gstaft_fnc +#ifdef _DO_INIT + = GetSystemTimeAsFileTime +#endif +; + +#endif + + + +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + typedef int64_t mbg_time_t; // we try to always use 64 bit types +#else + typedef time_t mbg_time_t; // fall back to the default +#endif + + + +static __mbg_inline /*HDR*/ +time_t cvt_to_time_t( mbg_time_t t ) +{ + // Eventually we can do some epoch check / conversion here. + return (time_t) t; + +} // cvt_to_time_t + + + +static __mbg_inline /*HDR*/ +int mbg_exp_time_t_to_time64_t( MBG_TIME64_T *p_t64, const time_t *p_t ) +{ + if ( sizeof( time_t ) == sizeof( MBG_TIME64_T ) ) + { + // No conversion required. + *p_t64 = *p_t; + return MBG_SUCCESS; + } + + // 'time_t' has 32 bits only. + + *p_t64 = (MBG_TIME64_T) (*p_t); + // FIXME TODO // Maybe we should do some + // epoch conversion / range mapping here. + + return MBG_SUCCESS; + +} // mbg_exp_time_t_to_time64_t + + + +static __mbg_inline /*HDR*/ +int mbg_trnc_time64_t_to_time_t( time_t *p_t, const MBG_TIME64_T *p_t64 ) +{ + int rc = MBG_SUCCESS; + + if ( sizeof( time_t ) == sizeof( MBG_TIME64_T ) ) + goto done; // No range check required. + + + if ( sizeof( time_t ) == sizeof( MBG_TIME32_T ) ) + { + // Must check if result in in range. + MBG_TIME64_T t64 = *p_t64; + int64_t upper_limit; + int64_t lower_limit; + + if ( ( (time_t) -1 ) > 0 ) // time_t is unsigned + { + upper_limit = 0xFFFFFFFFUL; + lower_limit = 0; + } + else // time_t is signed + { + upper_limit = 0x7FFFFFFFL; + lower_limit = 0x8000000L; + } + + if ( ( t64 > upper_limit ) || ( t64 < lower_limit ) ) + rc = MBG_ERR_OVERFLOW; + + goto done; + } + + rc = MBG_ERR_NOT_SUPP_ON_OS; + goto out; + + +done: + *p_t = (time_t) (*p_t64); + +out: + return rc; + +} // mbg_trnc_time64_t_to_time_t + + + +static __mbg_inline /*HDR*/ +int mbg_cvt_time32_t_to_time64_t( MBG_TIME64_T *p_t64, const MBG_TIME32_T *p_t32 ) +{ + // FIXME TODO Move the checks below to an extra inline function + // which does an epoch conversion, if required. + +#if 0 + // time_t should be at least 4 bytes + assert( sizeof( time_t ) >= 4 ); + + if ( sizeof( time_t ) == 4 ) + { + // 32 bit *signed* time_t will roll over after 2038-01-19 03:14:07 + // when the number of seconds reaches 0x7FFFFFFF, so we don't try + // conversions for 2038 or later, though 32 bit *unsigned* time_t + // may still work after year 2100. + if ( year < 70 || year > 137 ) + { + rc = MBG_ERR_RANGE; + goto out; + } + } + else + if ( sizeof( time_t ) == 8 ) + { + // 64 bit time_t will work for million years. However, it's not + // clear what happens for dates before 1970-01-01T00:00:00 if time_t + // is *unsigned*. + if ( year < 70 ) + { + rc = MBG_ERR_RANGE; + goto out; // TODO Eventually we can handle this + } + } + else + { + rc = MBG_ERR_NOT_SUPP_ON_OS; + goto out; + } +#endif + + return MBG_SUCCESS; + +} // mbg_cvt_time32_t_to_time64_t + + + + +static __mbg_inline /*HDR*/ +/** + * @brief A replacement function for POSIX @a gmtime. + * + * This function calls the original @a gmtime function, but unlike @a gmtime + * it expects the address of a <em>struct tm</em> variable which is only filled + * if @a gmtime completed successfully. An appropriate return code + * is provided, indicating if the conversion succeeded, or not. + * + * The original @a gmtime function returns a @a NULL pointer if the conversion + * fails, so a programs which just uses the pointer without checking it first + * may trap if the conversion fails. This can't happen with this function. + * + * This variant expects the address of a generic @a time_t variable. A @a time_t can + * be 32 bit or 64 bit wide, depending on the build environment and target system. + * Systems with 32 bit @a time_t will <b>suffer from the Y2038 problem</b>. + * + * There is also the ::mbg_gmtime64 variant, which expects a pointer to an + * ::MBG_TIME64_T variable to be converted, which is always 64 bits, even + * on 32 bit systems. + * + * @param[out] p_tm Address of a <em>struct tm</em> variable to take the conversion result. + * @param[in] p_t Address of a @a time_t variable to be converted. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_gmtime64 + */ +int mbg_gmtime( struct tm *p_tm, const time_t *p_t ) +{ + struct tm *p_tm_tmp = gmtime( p_t ); + + if ( p_tm_tmp == NULL ) // Conversion failed. + return mbg_get_last_error( NULL ); + + *p_tm = *p_tm_tmp; + + return MBG_SUCCESS; + +} // mbg_gmtime + + + +static __mbg_inline /*HDR*/ +/** + * @brief A replacement function for POSIX @a gmtime. + * + * This variant of ::mbg_gmtime expects a pointer to an ::MBG_TIME64_T variable + * to be converted, which is always 64 bits, even on 32 bit systems. + * + * Actually, the ::MBG_TIME64_T value is truncated to a native @a time_t, which can + * be 32 bit or 64 bit wide, depending on the build environment and target system. + * So this "just works" on systems with 64 bit @a time_t, but systems with 32 bit @a time_t + * will anyway suffer from the Y2038 problem, unless the @a gmtime call is replaced + * by a function that does a 64 bit conversion even on systems with 32 bit @a time_t. + * + * @param[out] p_tm Address of a <em>struct tm</em> variable to take the conversion result. + * @param[in] p_t64 Pointer to an ::MBG_TIME64_T providing the timestamp to be converted. + * + * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES + * + * @see ::mbg_gmtime + */ +int mbg_gmtime64( struct tm *p_tm, const MBG_TIME64_T *p_t64 ) +{ + struct tm *p_tm_tmp; + time_t t = cvt_to_time_t( *p_t64 ); + + // FIXME TODO Need to implement gmtime64() + // which always works with 64 bit timestamps. + p_tm_tmp = gmtime( &t ); + + if ( p_tm_tmp == NULL ) // Conversion failed. + return mbg_get_last_error( NULL ); + + *p_tm = *p_tm_tmp; + + return MBG_SUCCESS; + +} // mbg_gmtime64 + + + +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + +static __mbg_inline /*HDR*/ +double ntp_tstamp_to_double( const NTP_TSTAMP *t ) +{ + return (double) t->seconds + ( ( (double) t->fractions ) / NTP_FRAC_PER_SEC ); + +} // ntp_tstamp_to_double + + + +static __mbg_inline /*HDR*/ +ulong ntp_frac_to_nsec( uint32_t frac ) +{ + uint64_t tmp = ( (uint64_t) frac * NSEC_PER_SEC ) / NTP_FRAC_PER_SEC; + +#if 0 // TODO Currently not supported + if ( tmp >= NSEC_PER_SEC ) + mbglog( LOG_WARNING, "Range overflow in ntp_frac_to_nsec: 0x%X -> %Lu", + frac, tmp ); +#endif + + return (ulong) tmp; + +} // ntp_frac_to_nsec + + + +static __mbg_inline /*HDR*/ +uint32_t nsec_to_ntp_frac( ulong nsec ) +{ + uint64_t tmp; + + tmp = ( (uint64_t) nsec * NTP_FRAC_PER_SEC ) / NSEC_PER_SEC; + +#if 0 // TODO Currently not supported + if ( tmp >= NTP_FRAC_PER_SEC ) + mbglog( LOG_WARNING, "Range overflow in nsec_to_ntp_frac: %lu -> 0x%LX", + (ulong) nsec, tmp ); +#endif + + return (uint32_t) tmp; + +} // nsec_to_ntp_frac + + + +static __mbg_inline /*HDR*/ +void timespec_to_ntp_tstamp( NTP_TSTAMP *t_ntp, const struct timespec *t_ts ) +{ + t_ntp->seconds = (uint32_t) t_ts->tv_sec + NTP_SEC_BIAS; + t_ntp->fractions = nsec_to_ntp_frac( t_ts->tv_nsec ); + +} // timespec_to_ntp_tstamp + + + +static __mbg_inline /*HDR*/ +void ntp_tstamp_to_timespec( struct timespec *t_ts, const NTP_TSTAMP *t_ntp ) +{ + t_ts->tv_sec = t_ntp->seconds - NTP_SEC_BIAS; + t_ts->tv_nsec = ntp_frac_to_nsec( t_ntp->fractions ); + +} // ntp_tstamp_to_timespec + +#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + + + +static __mbg_inline /*HDR*/ +int timespec_is_set( const struct timespec *p ) +{ + return p->tv_sec != 0 || p->tv_nsec != 0; + +} // timespec_is_set + + + +// +// compute the difference of two timespec variables +// +static __mbg_inline /*HDR*/ +double delta_timespec_d_s( const struct timespec *ts, + const struct timespec *ts_ref ) +{ + return ( (double) ts->tv_sec - (double) ts_ref->tv_sec ) + + ( (double) ts->tv_nsec - (double) ts_ref->tv_nsec ) / NSEC_PER_SEC; + +} // delta_timespec_d_s + + + +#if !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + +static __mbg_inline /*HDR*/ +int64_t delta_timespec_ll_ns( const struct timespec *ts, + const struct timespec *ts_ref ) +{ + int64_t tmp = ts->tv_sec - ts_ref->tv_sec; + tmp = ( tmp * NSEC_PER_SEC ) + ( ts->tv_nsec - ts_ref->tv_nsec ); + + return tmp; + +} // delta_timespec_ll_ns + +#endif // !defined( MBG_TGT_MISSING_64_BIT_TYPES ) + + + +/* ----- function prototypes begin ----- */ + +/* This section was generated automatically */ +/* by MAKEHDR, do not remove the comments. */ + + int snprint_gmtime_error( char *s, size_t max_len, int mbg_errno, time_t t, const char *calling_fnc ) ; + /** + * @brief A Windows implementation for POSIX clock_gettime(). + * + * @param[in] clock_id Identifier of a specific clock, e.g. + * CLOCK_REALTIME, CLOCK_MONOTONIC, etc. + * @param[out] tp Address of a struct timespec to take up + * the current time. + * + * @return 0 on success, -1 on error, just like the POSIX function. + * In case of an error the POSIX errno variable is set + * appropriately. + */ + int mbg_clock_gettime( clockid_t clock_id, struct timespec *tp ) ; + + /** + * @brief A Windows implementation for POSIX clock_settime(). + * + * @param[in] clock_id Identifier of a specific clock, i.e. + * CLOCK_REALTIME which is the only clock + * supported by this call. + * @param[in] tp Pointer to a struct timespec providing + * the time to be set. + * + * @return 0 on success, -1 on error, just like the POSIX function. + * In case of an error the POSIX errno variable is set + * appropriately. + */ + int mbg_clock_settime( clockid_t clock_id, const struct timespec *tp ) ; + + void check_precise_time_api( void ) ; + /** + * @brief Print a %UTC offset into a string + * + * Format of the string is "[info]+hh[:mm[:ss]]h" + * + * @param[out] s Address of a string buffer to be filled. + * @param[in] max_len Size of the string buffer. + * @param[in] info An optional info string to be prepended, may be @a NULL. + * @param[in] utc_offs The %UTC offset to be printed, in [s]. + * + * @return The number of characters written to the output buffer, except the terminating 0. + */ + int snprint_utc_offs( char *s, size_t max_len, const char *info, long utc_offs ) ; + + int snprint_time_t_to_iso( time_t tstamp, int offs_hours, char *buf, size_t len ) ; + int snprint_time_t_to_iso_ms( time_t tstamp, int offs_hours, time_t frac, char *buf, size_t len ) ; + int snprint_time_t_to_iso_us( time_t tstamp, int offs_hours, time_t frac, char *buf, size_t len ) ; + int snprint_time_t_to_iso_ns( time_t tstamp, int offs_hours, time_t frac, char *buf, size_t len ) ; + int snprint_ntp_tstamp_to_iso_ms( const NTP_TSTAMP *ts, char *buf, size_t len ) ; + int snprint_ntp_tstamp_to_iso_us( const NTP_TSTAMP *ts, char *buf, size_t len ) ; + int snprint_ntp_tstamp_to_iso_ns( const NTP_TSTAMP *ts, char *buf, size_t len ) ; + +/* ----- function prototypes end ----- */ + +#ifdef __cplusplus +} +#endif + + +/* End of header body */ + +#undef _ext +#undef _DO_INIT + +#endif /* _TIMEUTIL_H */ diff --git a/c/mbglib/include/usbdefs.h b/c/mbglib/include/usbdefs.h index 9280d9f..3a5a37b 100644 --- a/c/mbglib/include/usbdefs.h +++ b/c/mbglib/include/usbdefs.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: usbdefs.h 1.21.1.4 2014/05/05 12:57:43Z paul TRASH $ + * $Id: usbdefs.h 1.44 2019/08/07 08:14:14Z daniel TEST $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,14 +10,68 @@ * * ----------------------------------------------------------------------- * $Log: usbdefs.h $ - * Revision 1.21.1.4 2014/05/05 12:57:43Z paul - * Added class code for SCG - * Revision 1.21.1.3 2014/04/10 12:56:29Z martin + * Revision 1.44 2019/08/07 08:14:14Z daniel + * Added support for GNS181_UC + * Revision 1.43 2019/07/31 13:55:56 martin + * Added support for FCU200. + * Revision 1.42 2019/06/19 08:41:19 martin + * Added support for RSC_02. + * Revision 1.41 2019/03/08 10:51:15 martin + * Added support for GNM181. + * Renamed class MBG_USB_CLASS_GRC to MBG_USB_CLASS_GNS. + * Revision 1.40 2019/01/14 08:37:45 martin + * GRC181 and GRC165 were preliminary names, so changed the + * associated definitions to GNS181 and GNS165 which are the + * final device names. + * Removed obsolete USYNCPWR stuff. + * Revision 1.39 2019/01/11 11:45:42 martin + * Added definitions for CPC200. + * Revision 1.38 2018/12/18 13:08:20 gregoire.diehl + * Added VSI180 + * Revision 1.37 2018/11/01 10:53:29Z martin + * Added some missing device name strings. + * Revision 1.36 2018/10/30 12:22:26 paul.kretz + * Added definitions for BPE_STM + * Revision 1.35 2018/09/07 13:04:47Z philipp + * Added USB_DEV_GRC165 which, in fact, is USB_DEV_GNS165 + * Revision 1.34 2017/12/12 07:37:47 philipp + * Added definitions for SSP100 + * Revision 1.33 2017/09/19 12:30:17 martin + * Added definitions for TCR180USB. + * Revision 1.32 2017/09/15 08:25:48 paul.kretz + * Added Class code and device ID for PIO180. + * Revision 1.31 2017/09/13 14:14:27Z paul.kretz + * Added ID, name string and table entry for FCM180 + * Revision 1.30 2017/05/17 09:52:53Z thomas.fasse + * Device BITS was rennamed to LSG180. + * Revision 1.29 2017/05/16 07:19:40Z thomas.fasse + * Added ID, name string and table entry for LIU variant BITS by Paul + * Revision 1.28 2017/04/04 10:43:34Z paul.kretz + * Added ID, name string and table entry for FDM180M + * Added missing table entry for MicroSync power supply module + * Revision 1.27 2017/03/28 09:37:15Z paul.kretz + * Added ID, name string and table entry for MicroSync power supply module + * Revision 1.26 2017/02/13 09:57:45Z paul.kretz + * Added ID, name string and table entry for PZF180. + * Revision 1.25 2016/11/11 09:24:04Z lars.meihost + * Added ID, name string and table entry for TCR180. + * Revision 1.24 2016/11/04 11:49:15Z paul.kretz + * Added device ID and associated class code for MDU312 + * Revision 1.23 2016/09/26 07:28:10Z paul.kretz + * Added class code and device for N2X180 + * Revision 1.22 2016/07/06 13:55:15Z martin + * Definitions for IMS-SPT, REL1000, MDU300, and SDI added by stephan. + * Class code and device ID for LUE added by daniel-vdh. + * Class code and device ID for HPS added by daniel. + * Device IDs and associated class codes for SCG, FDM180, CPC180, + * VSG180, and GTS180 added by paul. * Removed obsolete multiple definitions for FTDI serial interface chips. * Added a new definition for unique FTDI chip. - * Revision 1.21.1.2 2014/02/05 14:55:44 martin - * Revision 1.21.1.1 2014/01/24 13:02:18 martin - * Tmp. saved changes. + * Added definitions for serial refclocks. + * Added definitions for LNE180SFP, GRC180 and GRC181. + * Added definitions USB_VENDOR_WILDCARD and USB_PROD_WILDCARD. + * Added device name string and string table initializers. + * Doxygen fixes. * Revision 1.21 2014/01/16 15:26:09 daniel * Added class codes and devices for USB to serial adapters and ASIX network chips * Revision 1.20 2013/10/08 09:13:04 daniel @@ -82,37 +136,62 @@ extern "C" { /** Meinberg's USB vendor ID number (assigned by USB-IF administration) */ #define USB_VENDOR_MEINBERG 0x1938 +#define USB_VENDOR_WILDCARD 0 +#define USB_PROD_WILDCARD 0 + /** * @brief USB device class codes assigned by Meinberg */ enum MBG_USB_CLASS_CODES { - MBG_USB_CLASS_NONE, // (unknown or not defined) - MBG_USB_CLASS_CPC, // Control Panel Controller - MBG_USB_CLASS_TSU, // Time Stamp Unit - MBG_USB_CLASS_DCF, // DCF77 Radio Clock - MBG_USB_CLASS_CMC, // nCipher Crypto Module Carrier - MBG_USB_CLASS_TCR, // IRIG Time Code Receiver - MBG_USB_CLASS_MSF, // MSF Radio Clock - MBG_USB_CLASS_WWVB, // WWVB Radio Clock - MBG_USB_CLASS_SCU, // Meinberg Signal Changeover Unit - MBG_USB_CLASS_ESI, // External Synchronization Interface - MBG_USB_CLASS_FCU, // Fan Control Unit - MBG_USB_CLASS_CPE, // Configurable Port Expander - MBG_USB_CLASS_GPS, // GPS Receiver - MBG_USB_CLASS_LNO, // Low Phase Noise Option - MBG_USB_CLASS_LIU, // Line Interface Unit - MBG_USB_CLASS_LNE, // LNE-GB - MBG_USB_CLASS_MRI, // MRS Input card for IMS - MBG_USB_CLASS_BPE, // IMS Backplane Port Expander - MBG_USB_CLASS_RSC, // RSC Redundant Switch Control - MBG_USB_CLASS_SERIAL, // USB to Serial controller - MBG_USB_CLASS_SCG, // Studio Clock Generator - - MBG_USB_CLASS_NIC = 0x17, // ASIX AX88179 Network interface chips on LNE - - N_MBG_USB_CLASS // number of known device class codes + MBG_USB_CLASS_NONE, ///< (unknown or not defined) + MBG_USB_CLASS_CPC, ///< Control Panel Controller + MBG_USB_CLASS_TSU, ///< Time Stamp Unit + MBG_USB_CLASS_DCF, ///< DCF77 Radio Clock + MBG_USB_CLASS_CMC, ///< nCipher Crypto Module Carrier + MBG_USB_CLASS_TCR, ///< IRIG Time Code Receiver + MBG_USB_CLASS_MSF, ///< MSF Radio Clock + MBG_USB_CLASS_WWVB, ///< WWVB Radio Clock + + MBG_USB_CLASS_SCU, ///< Meinberg Signal Changeover Unit + MBG_USB_CLASS_ESI, ///< External Synchronization Interface + MBG_USB_CLASS_FCU, ///< Fan Control Unit + MBG_USB_CLASS_CPE, ///< Configurable Port Expander + MBG_USB_CLASS_GPS, ///< GPS Receiver + MBG_USB_CLASS_LNO, ///< Low Phase Noise Option + MBG_USB_CLASS_LIU, ///< Line Interface Unit + MBG_USB_CLASS_LNE, ///< LNE-GB + + MBG_USB_CLASS_MRI, ///< MRS Input card for IMS + MBG_USB_CLASS_BPE, ///< IMS Backplane Port Expander + MBG_USB_CLASS_RSC, ///< RSC Redundant Switch Control + MBG_USB_CLASS_SERIAL, ///< USB to Serial controller, FTDI chip connected to Meinberg serial device + MBG_USB_CLASS_SCG, ///< Studio Clock Generator + MBG_USB_CLASS_SDI, ///< SDI Input card for IMS + MBG_USB_CLASS_FDM, ///< Frequency Deviation Monitor + MBG_USB_CLASS_NIC, ///< ASIX AX88179 Network interface chips on LNE, modified by Meinberg (this ***must*** be 0x17) + + MBG_USB_CLASS_MDU, ///< Modular Distribution Unit + MBG_USB_CLASS_SPT, ///< Single Path Through + MBG_USB_CLASS_REL, ///< Relais Error Card + MBG_USB_CLASS_LUE, ///< Lantime USB Expansion + MBG_USB_CLASS_HPS, ///< High Performance Synchronization Card (PTP/NTP) + MBG_USB_CLASS_VSG, ///< Video Sync Generator + MBG_USB_CLASS_GTS, ///< Greenwich Time Signal + MBG_USB_CLASS_GNS, ///< GNSS receivers (GPS, GLONASS, ... ) + + MBG_USB_CLASS_N2X, ///< NTP/PTP receiver + MBG_USB_CLASS_PLACEHOLDER, // TODO formerly this was MBG_USB_CLASS_USYNC, used with USYNCPWR. + // This is obsolete, but we need to keep an entry here to preserve + // the numeric values of subsequent symbols. + // When another new class needs to be defined, the class can be + // defined in place here, and MBG_USB_CLASS_PLACEHOLDER can be removed. + MBG_USB_CLASS_FCM, ///< Fake Clock Module + MBG_USB_CLASS_PIO, ///< Programmable Input/Output Module + MBG_USB_CLASS_VSI, ///< Video Sync Interface + + N_MBG_USB_CLASS ///< number of known Meinberg USB device class codes }; @@ -122,103 +201,282 @@ enum MBG_USB_CLASS_CODES * High byte: USB device class, see ::MBG_USB_CLASS_CODES<br> * Low byte: enumeration of devices of a class * - * @anchor MBG_USB_DEVICE_IDS @{ */ + * @see @ref MBG_USB_DEVICE_NAMES + * @see ::DEFAULT_MBG_USB_DEVICE_NAMES + * @see ::MBG_USB_CLASS_CODES + * + * @anchor MBG_USB_DEVICE_IDS @{ + */ + +// If new devices are defined here then appropriate definitions should also +// be added to MBG_USB_DEVICE_NAMES and DEFAULT_MBG_USB_DEVICE_NAMES. -#define USB_DEV_CPC_01 ( ( MBG_USB_CLASS_CPC << 8 ) | 0x01 ) +#define USB_DEV_CPC_01 ( ( MBG_USB_CLASS_CPC << 8 ) | 0x01 ) +#define USB_DEV_CPC180 ( ( MBG_USB_CLASS_CPC << 8 ) | 0x02 ) +#define USB_DEV_CPC200 ( ( MBG_USB_CLASS_CPC << 8 ) | 0x03 ) -#define USB_DEV_TSU_01 ( ( MBG_USB_CLASS_TSU << 8 ) | 0x01 ) +#define USB_DEV_TSU_01 ( ( MBG_USB_CLASS_TSU << 8 ) | 0x01 ) -#define USB_DEV_USB5131 ( ( MBG_USB_CLASS_DCF << 8 ) | 0x01 ) -#define USB_DEV_DCF600USB ( ( MBG_USB_CLASS_DCF << 8 ) | 0x02 ) +#define USB_DEV_USB5131 ( ( MBG_USB_CLASS_DCF << 8 ) | 0x01 ) +#define USB_DEV_DCF600USB ( ( MBG_USB_CLASS_DCF << 8 ) | 0x02 ) +#define USB_DEV_PZF180 ( ( MBG_USB_CLASS_DCF << 8 ) | 0x03 ) -#define USB_DEV_CMC ( ( MBG_USB_CLASS_CMC << 8 ) | 0x01 ) +#define USB_DEV_CMC ( ( MBG_USB_CLASS_CMC << 8 ) | 0x01 ) -#define USB_DEV_TCR51USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x01 ) -#define USB_DEV_TCR600USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x02 ) +#define USB_DEV_TCR51USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x01 ) +#define USB_DEV_TCR600USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x02 ) +#define USB_DEV_TCR180 ( ( MBG_USB_CLASS_TCR << 8 ) | 0x03 ) +#define USB_DEV_TCR180USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x04 ) -#define USB_DEV_MSF51USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x01 ) -#define USB_DEV_MSF600USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x02 ) +#define USB_DEV_MSF51USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x01 ) +#define USB_DEV_MSF600USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x02 ) -#define USB_DEV_WWVB51USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x01 ) -#define USB_DEV_WVB600USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x02 ) +#define USB_DEV_WWVB51USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x01 ) +#define USB_DEV_WVB600USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x02 ) -#define USB_DEV_SCU_USB ( ( MBG_USB_CLASS_SCU << 8 ) | 0x01 ) +#define USB_DEV_SCU_USB ( ( MBG_USB_CLASS_SCU << 8 ) | 0x01 ) -#define USB_DEV_ESI_01 ( ( MBG_USB_CLASS_ESI << 8 ) | 0x01 ) +#define USB_DEV_ESI_01 ( ( MBG_USB_CLASS_ESI << 8 ) | 0x01 ) -#define USB_DEV_FCU_01 ( ( MBG_USB_CLASS_FCU << 8 ) | 0x01 ) +#define USB_DEV_FCU_01 ( ( MBG_USB_CLASS_FCU << 8 ) | 0x01 ) // Fan (and power supply) Control Unit, doesn't support FCU API. +#define USB_DEV_FCU200 ( ( MBG_USB_CLASS_FCU << 8 ) | 0x02 ) // Fan (and power supply) Control Unit, supports FCU API. -#define USB_DEV_CPE_01 ( ( MBG_USB_CLASS_CPE << 8 ) | 0x01 ) +#define USB_DEV_CPE_01 ( ( MBG_USB_CLASS_CPE << 8 ) | 0x01 ) -#define USB_DEV_GPS180 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x01 ) +#define USB_DEV_GPS180 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x01 ) -#define USB_DEV_LNO180_01 ( ( MBG_USB_CLASS_LNO << 8 ) | 0x01 ) +#define USB_DEV_LNO180 ( ( MBG_USB_CLASS_LNO << 8 ) | 0x01 ) -#define USB_DEV_LIU_01 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x01 ) +#define USB_DEV_LIU_01 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x01 ) +#define USB_DEV_LSG180 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x02 ) -#define USB_DEV_LNE_01 ( ( MBG_USB_CLASS_LNE << 8 ) | 0x01 ) +#define USB_DEV_LNE_01 ( ( MBG_USB_CLASS_LNE << 8 ) | 0x01 ) // LNE with standard copper +#define USB_DEV_LNE180SFP ( ( MBG_USB_CLASS_LNE << 8 ) | 0x02 ) // LNE with SFP (fiber optic) -#define USB_DEV_MRI_01 ( ( MBG_USB_CLASS_MRI << 8 ) | 0x01 ) +#define USB_DEV_MRI_01 ( ( MBG_USB_CLASS_MRI << 8 ) | 0x01 ) -#define USB_DEV_BPE_01 ( ( MBG_USB_CLASS_BPE << 8 ) | 0x01 ) +#define USB_DEV_BPE_01 ( ( MBG_USB_CLASS_BPE << 8 ) | 0x01 ) // BPE with ATMEL M3 +#define USB_DEV_BPE_STM ( ( MBG_USB_CLASS_BPE << 8 ) | 0x02 ) // BPE with STM M0 -#define USB_DEV_RSC_01 ( ( MBG_USB_CLASS_RSC << 8 ) | 0x01 ) +#define USB_DEV_RSC_01 ( ( MBG_USB_CLASS_RSC << 8 ) | 0x01 ) // RSC used with M1000 / M3000 / IMS +#define USB_DEV_RSC_02 ( ( MBG_USB_CLASS_RSC << 8 ) | 0x02 ) // RSC used with M2000 + +#define USB_DEV_SPT_01 ( ( MBG_USB_CLASS_SPT << 8 ) | 0x01 ) + +#define USB_DEV_REL_01 ( ( MBG_USB_CLASS_REL << 8 ) | 0x01 ) /// LANTIME CPU quad FTDI serial interface chip -#define USB_DEV_LAN_CPU_SERIAL ( ( MBG_USB_CLASS_SERIAL << 8 ) | 0x01 ) +#define USB_DEV_LAN_CPU_SERIAL ( ( MBG_USB_CLASS_SERIAL << 8 ) | 0x01 ) + +#define USB_DEV_SCG_01 ( ( MBG_USB_CLASS_SCG << 8 ) | 0x01 ) + +#define USB_DEV_SDI_01 ( ( MBG_USB_CLASS_SDI << 8 ) | 0x01 ) + +#define USB_DEV_FDM180 ( ( MBG_USB_CLASS_FDM << 8 ) | 0x01 ) ///< FDM for IMS Systems +#define USB_DEV_FDM180M ( ( MBG_USB_CLASS_FDM << 8 ) | 0x02 ) ///< FDM for old Lantime Systems (M300/M600/M900) + +#define USB_DEV_MDU300 ( ( MBG_USB_CLASS_MDU << 8 ) | 0x01 ) +#define USB_DEV_MDU312 ( ( MBG_USB_CLASS_MDU << 8 ) | 0x02 ) + +#define USB_DEV_LUE_01 ( ( MBG_USB_CLASS_LUE << 8 ) | 0x01 ) + +#define USB_DEV_HPS100 ( ( MBG_USB_CLASS_HPS << 8 ) | 0x01 ) +#define USB_DEV_SSP100 ( ( MBG_USB_CLASS_HPS << 8 ) | 0x02 ) + +#define USB_DEV_VSG180 ( ( MBG_USB_CLASS_VSG << 8 ) | 0x01 ) + +#define USB_DEV_VSI180 ( ( MBG_USB_CLASS_VSI << 8 ) | 0x01 ) -#define USB_DEV_SCG_01 ( ( MBG_USB_CLASS_SCG << 8 ) | 0x01 ) +#define USB_DEV_GTS180 ( ( MBG_USB_CLASS_GTS << 8 ) | 0x01 ) + +#define USB_DEV_GRC180 ( ( MBG_USB_CLASS_GNS << 8 ) | 0x01 ) +#define USB_DEV_GNS181 ( ( MBG_USB_CLASS_GNS << 8 ) | 0x02 ) +#define USB_DEV_GNS165 ( ( MBG_USB_CLASS_GNS << 8 ) | 0x03 ) +#define USB_DEV_GNM181 ( ( MBG_USB_CLASS_GNS << 8 ) | 0x04 ) +#define USB_DEV_GNS181_UC ( ( MBG_USB_CLASS_GNS << 8 ) | 0x05 ) + +#define USB_DEV_N2X180 ( ( MBG_USB_CLASS_N2X << 8 ) | 0x01 ) + +#define USB_DEV_FCM180 ( ( MBG_USB_CLASS_FCM << 8 ) | 0x01 ) ///< Fake Clock Module + +#define USB_DEV_PIO180 ( ( MBG_USB_CLASS_PIO << 8 ) | 0x01 ) ///< Programmable Input/Output Module + +// If new devices are defined here then appropriate definitions should also +// be added to MBG_USB_DEVICE_NAMES and DEFAULT_MBG_USB_DEVICE_NAMES. /** @} anchor MBG_USB_DEVICE_IDS */ + /** * @brief Device name strings for Meinberg USB devices * * @see @ref MBG_USB_DEVICE_IDS + * @see ::DEFAULT_MBG_USB_DEVICE_NAMES * - * @anchor MBG_USB_DEVICE_NAMES @{ */ + * @anchor MBG_USB_DEVICE_NAMES @{ + */ -#if 0 //##++++++++++++ TODO +#define USB_DEV_NAME_CPC_01 "CPC_01" +#define USB_DEV_NAME_CPC180 "CPC180" +#define USB_DEV_NAME_CPC200 "CPC200" -#define USB_DEV_CPC_01 ( ( MBG_USB_CLASS_CPC << 8 ) | 0x01 ) -#define USB_DEV_TSU_01 ( ( MBG_USB_CLASS_TSU << 8 ) | 0x01 ) -#define USB_DEV_USB5131 ( ( MBG_USB_CLASS_DCF << 8 ) | 0x01 ) -#define USB_DEV_DCF600USB ( ( MBG_USB_CLASS_DCF << 8 ) | 0x02 ) -#define USB_DEV_CMC ( ( MBG_USB_CLASS_CMC << 8 ) | 0x01 ) -#define USB_DEV_TCR51USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x01 ) -#define USB_DEV_TCR600USB ( ( MBG_USB_CLASS_TCR << 8 ) | 0x02 ) -#define USB_DEV_MSF51USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x01 ) -#define USB_DEV_MSF600USB ( ( MBG_USB_CLASS_MSF << 8 ) | 0x02 ) -#define USB_DEV_WWVB51USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x01 ) -#define USB_DEV_WVB600USB ( ( MBG_USB_CLASS_WWVB << 8 ) | 0x02 ) -#define USB_DEV_SCU_USB ( ( MBG_USB_CLASS_SCU << 8 ) | 0x01 ) -#define USB_DEV_ESI_01 ( ( MBG_USB_CLASS_ESI << 8 ) | 0x01 ) -#define USB_DEV_FCU_01 ( ( MBG_USB_CLASS_FCU << 8 ) | 0x01 ) +#define USB_DEV_NAME_TSU_01 "TSU_01" -#define USB_DEV_CPE_01 ( ( MBG_USB_CLASS_CPE << 8 ) | 0x01 ) +#define USB_DEV_NAME_USB5131 "USB5131" +#define USB_DEV_NAME_DCF600USB "DCF600USB" +#define USB_DEV_NAME_PZF180 "PZF180" -#define USB_DEV_GPS180 ( ( MBG_USB_CLASS_GPS << 8 ) | 0x01 ) +#define USB_DEV_NAME_CMC "CMC" -#define USB_DEV_LNO180_01 ( ( MBG_USB_CLASS_LNO << 8 ) | 0x01 ) +#define USB_DEV_NAME_TCR51USB "TCR51USB" +#define USB_DEV_NAME_TCR600USB "TCR600USB" +#define USB_DEV_NAME_TCR180 "TCR180" +#define USB_DEV_NAME_TCR180USB "TCR180USB" -#define USB_DEV_LIU_01 ( ( MBG_USB_CLASS_LIU << 8 ) | 0x01 ) +#define USB_DEV_NAME_MSF51USB "MSF51USB" +#define USB_DEV_NAME_MSF600USB "MSF600USB" -#define USB_DEV_LNE_01 ( ( MBG_USB_CLASS_LNE << 8 ) | 0x01 ) +#define USB_DEV_NAME_WWVB51USB "WWVB51USB" +#define USB_DEV_NAME_WVB600USB "WVB600USB" -#define USB_DEV_MRI_01 ( ( MBG_USB_CLASS_MRI << 8 ) | 0x01 ) +#define USB_DEV_NAME_SCU_USB "SCU_USB" -#define USB_DEV_BPE_01 ( ( MBG_USB_CLASS_BPE << 8 ) | 0x01 ) +#define USB_DEV_NAME_ESI_01 "ESI_01" -#define USB_DEV_RSC_01 ( ( MBG_USB_CLASS_RSC << 8 ) | 0x01 ) +#define USB_DEV_NAME_FCU_01 "FCU_01" +#define USB_DEV_NAME_FCU200 "FCU200" -#define USB_DEV_LAN_CPU_SERIAL ( ( MBG_USB_CLASS_SERIAL << 8 ) | 0x01 ) +#define USB_DEV_NAME_CPE_01 "CPE_01" -#endif +#define USB_DEV_NAME_GPS180 "GPS180" + +#define USB_DEV_NAME_LNO180 "LNO180" + +#define USB_DEV_NAME_LIU_01 "LIU_01" +#define USB_DEV_NAME_LSG180 "LSG180" + +#define USB_DEV_NAME_LNE_01 "LNE_01" +#define USB_DEV_NAME_LNE180SFP "LNE180SFP" + +#define USB_DEV_NAME_MRI_01 "MRI_01" + +#define USB_DEV_NAME_BPE_01 "BPE_01" +#define USB_DEV_NAME_BPE_STM "BPE" + +#define USB_DEV_NAME_RSC_01 "RSC_01" +#define USB_DEV_NAME_RSC_02 "RSC_02" + +#define USB_DEV_NAME_SPT_01 "SPT_01" + +#define USB_DEV_NAME_REL_01 "REL_01" + +#define USB_DEV_NAME_LAN_CPU_SERIAL "LAN_CPU_SERIAL" + +#define USB_DEV_NAME_SCG_01 "SCG_01" + +#define USB_DEV_NAME_SDI_01 "SDI_01" + +#define USB_DEV_NAME_FDM180 "FDM180" +#define USB_DEV_NAME_FDM180M "FDM180M" + +#define USB_DEV_NAME_MDU300 "MDU300" +#define USB_DEV_NAME_MDU312 "MDU312" + +#define USB_DEV_NAME_LUE_01 "LUE_01" + +#define USB_DEV_NAME_HPS100 "HPS100" +#define USB_DEV_NAME_SSP100 "SSP100" + +#define USB_DEV_NAME_VSG180 "VSG180" +#define USB_DEV_NAME_VSI180 "VSI180" + +#define USB_DEV_NAME_GTS180 "GTS180" + +#define USB_DEV_NAME_GRC180 "GRC180" +#define USB_DEV_NAME_GNS181 "GNS181" +#define USB_DEV_NAME_GNS165 "GNS165" +#define USB_DEV_NAME_GNM181 "GNM181" + +#define USB_DEV_NAME_N2X180 "N2X180" + +#define USB_DEV_NAME_FCM180 "FCM180" + +#define USB_DEV_NAME_PIO180 "PIO180" /** @} anchor MBG_USB_DEVICE_NAMES */ + +/** + * @brief Initializer for a table of USB device IDs and name strings + * + * Can be used e.g. to initialize an array of ::MBG_CODE_NAME_TABLE_ENTRY. + * + * @see @ref MBG_USB_DEVICE_IDS + * @see @ref MBG_USB_DEVICE_NAMES + */ +#define DEFAULT_MBG_USB_DEVICE_NAMES \ +{ \ + { USB_DEV_CPC_01, USB_DEV_NAME_CPC_01 }, \ + { USB_DEV_CPC180, USB_DEV_NAME_CPC180 }, \ + { USB_DEV_TSU_01, USB_DEV_NAME_TSU_01 }, \ + { USB_DEV_USB5131, USB_DEV_NAME_USB5131 }, \ + { USB_DEV_DCF600USB, USB_DEV_NAME_DCF600USB }, \ + { USB_DEV_CMC, USB_DEV_NAME_CMC }, \ + { USB_DEV_TCR51USB, USB_DEV_NAME_TCR51USB }, \ + { USB_DEV_TCR600USB, USB_DEV_NAME_TCR600USB }, \ + { USB_DEV_TCR180, USB_DEV_NAME_TCR180 }, \ + { USB_DEV_MSF51USB, USB_DEV_NAME_MSF51USB }, \ + { USB_DEV_MSF600USB, USB_DEV_NAME_MSF600USB }, \ + { USB_DEV_WWVB51USB, USB_DEV_NAME_WWVB51USB }, \ + { USB_DEV_WVB600USB, USB_DEV_NAME_WVB600USB }, \ + { USB_DEV_SCU_USB, USB_DEV_NAME_SCU_USB }, \ + { USB_DEV_ESI_01, USB_DEV_NAME_ESI_01 }, \ + { USB_DEV_FCU_01, USB_DEV_NAME_FCU_01 }, \ + { USB_DEV_CPE_01, USB_DEV_NAME_CPE_01 }, \ + { USB_DEV_GPS180, USB_DEV_NAME_GPS180 }, \ + { USB_DEV_LNO180, USB_DEV_NAME_LNO180 }, \ + { USB_DEV_LIU_01, USB_DEV_NAME_LIU_01 }, \ + { USB_DEV_LNE_01, USB_DEV_NAME_LNE_01 }, \ + { USB_DEV_MRI_01, USB_DEV_NAME_MRI_01 }, \ + { USB_DEV_BPE_01, USB_DEV_NAME_BPE_01 }, \ + { USB_DEV_RSC_01, USB_DEV_NAME_RSC_01 }, \ + { USB_DEV_SPT_01, USB_DEV_NAME_SPT_01 }, \ + { USB_DEV_REL_01, USB_DEV_NAME_REL_01 }, \ + { USB_DEV_LAN_CPU_SERIAL, USB_DEV_NAME_LAN_CPU_SERIAL }, \ + { USB_DEV_SCG_01, USB_DEV_NAME_SCG_01 }, \ + { USB_DEV_SDI_01, USB_DEV_NAME_SDI_01 }, \ + { USB_DEV_FDM180, USB_DEV_NAME_FDM180 }, \ + { USB_DEV_MDU300, USB_DEV_NAME_MDU300 }, \ + { USB_DEV_LUE_01, USB_DEV_NAME_LUE_01 }, \ + { USB_DEV_HPS100, USB_DEV_NAME_HPS100 }, \ + { USB_DEV_VSG180, USB_DEV_NAME_VSG180 }, \ + { USB_DEV_LNE180SFP, USB_DEV_NAME_LNE180SFP }, \ + { USB_DEV_GTS180, USB_DEV_NAME_GTS180 }, \ + { USB_DEV_GRC180, USB_DEV_NAME_GRC180 }, \ + { USB_DEV_GNS181, USB_DEV_NAME_GNS181 }, \ + { USB_DEV_N2X180, USB_DEV_NAME_N2X180 }, \ + { USB_DEV_MDU312, USB_DEV_NAME_MDU312 }, \ + { USB_DEV_PZF180, USB_DEV_NAME_PZF180 }, \ + { USB_DEV_FDM180M, USB_DEV_NAME_FDM180M }, \ + { USB_DEV_LSG180, USB_DEV_NAME_LSG180 }, \ + { USB_DEV_FCM180, USB_DEV_NAME_FCM180 }, \ + { USB_DEV_PIO180, USB_DEV_NAME_PIO180 }, \ + { USB_DEV_TCR180USB, USB_DEV_NAME_TCR180USB }, \ + { USB_DEV_SSP100, USB_DEV_NAME_SSP100 }, \ + { USB_DEV_GNS165, USB_DEV_NAME_GNS165 }, \ + { USB_DEV_BPE_STM, USB_DEV_NAME_BPE_STM }, \ + { USB_DEV_VSI180, USB_DEV_NAME_VSI180 }, \ + { USB_DEV_CPC200, USB_DEV_NAME_CPC200 }, \ + { USB_DEV_GNM181, USB_DEV_NAME_GNM181 }, \ + { USB_DEV_RSC_02, USB_DEV_NAME_RSC_02 }, \ + { USB_DEV_FCU200, USB_DEV_NAME_FCU200 }, \ + { 0, /* end of table */ NULL } \ +} + + + enum { MBGUSB_EP_IDX_HOST_IN, // transfers from device to host diff --git a/c/mbglib/include/wingetopt.h b/c/mbglib/include/wingetopt.h new file mode 100644 index 0000000..f983fb3 --- /dev/null +++ b/c/mbglib/include/wingetopt.h @@ -0,0 +1,32 @@ +/* +POSIX getopt for Windows + +AT&T Public License + +Code given out at the 1985 UNIFORUM conference in Dallas. +*/ + +#ifdef __GNUC__ +#include <getopt.h> +#endif +#ifndef __GNUC__ + +#ifndef _WINGETOPT_H_ +#define _WINGETOPT_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +extern int opterr; +extern int optind; +extern int optopt; +extern char *optarg; +extern int getopt(int argc, char **argv, char *opts); + +#ifdef __cplusplus +} +#endif + +#endif /* _GETOPT_H_ */ +#endif /* __GNUC__ */ diff --git a/c/mbglib/include/words.h b/c/mbglib/include/words.h index d41fe76..8401a5b 100644 --- a/c/mbglib/include/words.h +++ b/c/mbglib/include/words.h @@ -1,7 +1,7 @@ /************************************************************************** * - * $Id: words.h 1.33 2014/05/27 10:18:35Z martin REL_M $ + * $Id: words.h 1.49 2019/10/23 08:31:48Z thomas-b REL_M $ * * Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany * @@ -10,6 +10,47 @@ * * ----------------------------------------------------------------------- * $Log: words.h $ + * Revision 1.49 2019/10/23 08:31:48Z thomas-b + * Added struct name for NANO_TIME_64 + * Revision 1.48 2019/06/17 08:38:59 thomas-b + * Renamed structs according to Meinberg naming convention + * Revision 1.47 2019/06/06 12:17:14 thomas-b + * Added several struct names to allow forward declaration + * Revision 1.46 2019/02/07 14:38:56 martin + * Removed a duplicate definition. + * Revision 1.45 2018/11/22 16:38:15 martin + * Removed inclusion of mbg_no_tgt.h which is obsolete here. + * Revision 1.44 2018/06/25 09:21:02 martin + * Support MBG_TGT_NO_TGT. + * Improved STRINGIFY() macro. + * Revision 1.43 2018/01/29 10:30:23 martin + * Modified some comments. + * Revision 1.42 2017/07/26 14:28:50Z martin + * Fixed build for NetBSD. + * Revision 1.41 2017/07/05 12:06:35 martin + * Moved macro _int_from_size_t() here. + * Revision 1.40 2017/06/12 11:14:25 martin + * Empty _DEPRECATED_BY definition for firmware targets. + * Revision 1.39 2017/03/15 10:01:09 martin + * Added comments how to represent negative numbers in NANO_TIME + * and NANO_TIME_64 structures. + * Added macros _nano_time_zero() and _nano_time_64_zero(). + * Revision 1.38 2017/02/22 11:56:33 martin + * Made MBG_CODE_NAME_TABLE_ENTRY::code signed to + * avoid signed/unsigned warnings with some code tables. + * Revision 1.37 2017/01/27 12:24:35Z martin + * Moved STRINGIFY() macro here. + * Revision 1.36 2017/01/27 08:59:43 martin + * Fixed macro syntax. + * Revision 1.35 2016/08/05 12:17:21 martin + * Moved definitions for NANO_TIME and NANO_TIME_64 here. + * New macro _nano_time_64_negative(). + * Conditionally define _abs64() macro. + * Include <inttypes.h> for Keil ARMCC target. + * Added some conditional debugging code. + * Fixed some spelling. + * Revision 1.34 2014/10/20 12:31:20 martin + * Moved macro _isdigit() here. * Revision 1.33 2014/05/27 10:18:35Z martin * Finer control of which types are required for or already * available on particular target systems. @@ -121,11 +162,16 @@ #if defined( __ARMCC_VERSION ) // Keil RealView Compiler for ARM #define __mbg_inline __inline #include <stdint.h> + #include <inttypes.h> #include <stdbool.h> #define MBG_TGT_HAS_EXACT_SIZE_TYPES 1 #else #define MBG_TGT_MISSING_64_BIT_TYPES 1 #endif + + #if !defined( _DEPRECATED_BY ) + #define _DEPRECATED_BY( _s ) // empty definition + #endif #endif @@ -192,9 +238,9 @@ #if defined( MBG_TGT_MISSING_64_BIT_TYPES ) // The build environment does not support 64 bit types. However, - // 64 bit types need to be defined to avoid build errors + // 64 bit types need to be defined to avoid build errors e.g. // if these types are formally used in function prototypes. - // We explicitely use abnormal data types to hopefully + // We explicitly use abnormal data types to hopefully // cause compiler errors in case these types are // unexpectedly used to generate real code for a target // platform which does not support 64 bit types. @@ -204,8 +250,8 @@ #else // Define C99 types using non-standard exact-size types - // which are usually supported by build envonronments - // supporting 64 bit types but no C99 types. + // which are usually supported by build environments that + // support 64 bit types but don't support C99 types. typedef __int64 int64_t; typedef unsigned __int64 uint64_t; @@ -223,6 +269,10 @@ #define MBG_TGT_HAS_64BIT_TYPES 1 + #if !defined( MBG_TGT_HAS_ABS64 ) + #define _abs64( _i ) ( (int64_t) ( ( (_i) < 0 ) ? -(_i) : (_i) ) ) + #endif + #endif @@ -275,34 +325,110 @@ #endif -#if !defined( _BIT_DEFINED ) +#if defined( MBG_TGT_MISSING_BOOL_TYPE ) + //#error MBG_TGT_MISSING_BOOL_TYPE is defined + // BDS/Borland C++ Builder 2006 (non-C++ mode) + // Borland C++ Builder 5 (non-C++ mode) + // BC 3.1 + // VC6 + // DDKbuild + // VS2008 +#endif - // We need to implement a "bit" type. Preferably we use "bool" - // to do this, but this is only supported by C++ compilers, and - // by C compilers supporting the C99 standard. +#if defined( __cplusplus ) + //#error __cplusplus is defined +#endif - #if !defined( MBG_TGT_MISSING_BOOL_TYPE ) && \ - ( defined( __cplusplus ) || defined( __bool_true_false_are_defined ) ) +#if defined( __bool_true_false_are_defined ) + //#error __bool_true_false_are_defined is defined + // Keil armcc + // gcc / Linux user space + // clang / FreeBSD user space and kernel +#endif - typedef bool bit; - #define bit bit - #else // C99 types not supported +#if defined( MBG_TGT_MISSING_BOOL_TYPE ) /* from mbg_tgt.h */ \ + || ( !defined( __cplusplus ) /* C++ */ \ + && !defined( __bool_true_false_are_defined ) /* C99 */ \ + && !defined( _LINUX_TYPES_H ) ) /* Linux kernel */ \ + && !( defined( MBG_TGT_NETBSD ) && defined( _SYS_TYPES_H_ ) ) /* NetBSD kernel */ - // Falling back to use "int" for "bit". This prevents error - // messages if "bit" is used in function prototypes, but may - // yield unexpected results for code like: - // return (bit) ( val & 0x10 ); - typedef int bit; - #define bit bit + // There's no native support for a "bool" type, so we + // need a substitute. + #if defined( _BIT_DEFINED ) + // A native "bit" type is supported, so we use it for bool. + //#error substituting bit for bool + // C166 + typedef bit bool; + #else + // Fall back to "int". This is just a hack which + // may yield unexpected results with code like: + // return (bool) ( val & 0x10 ); + // A safe way of coding would be: + // return (bool) ( ( val & 0x10 ) != 0 ); + //#error substituting int for bool + // Borland C++ Builder 5 + // BC 3.1 + // VC6 + // DDKbuild + // VS2008 + typedef int bool; #endif + // Eventually provoke a build error if the build + // environment unexpectedly supports "bool" natively. + #define bool bool + #define true 1 + #define false 0 +#else + //#error native bool type supported + // Borland C++ Builder 5 and newer (C++ mode only) + // Keil armcc + // gcc / Linux user space + // gcc / Linux kernel + // clang / FreeBSD user space and kernel +#endif + + +#if !defined( _BIT_DEFINED ) + + // There's no native support for a "bit" type, so we + // need a substitute. The "bool" type would fit best + // and should be fine if it's supported natively. + // + // However, if "bool" has been substituted above + // by "int"then this is just a hack which may yield + // unexpected results with code like: + // return (bit) ( val & 0x10 ); + // A safe way of coding would be: + // return (bit) ( ( val & 0x10 ) != 0 ); + + //#error substituting bool for bit + // Keil armcc + // Borland C++ Builder 5 + // BC 3.1 + // VC6 + // DDKbuild + // VS2008 + // gcc / Linux user space + // gcc / Linux kernel + // clang / FreeBSD user space and kernel + typedef bool bit; + + // Eventually provoke a build error if the build + // environment unexpectedly supports "bit" natively. + #define bit bit + #define _BIT_REDEFINED 1 +#else + //#error native bit type supported + // C166 #endif + #define BYTE_0( _x ) ( (uint8_t ) ( (_x) & 0xFF ) ) #define BYTE_1( _x ) ( (uint8_t ) ( ( ( (uint16_t) (_x) ) >> 8 ) & 0xFF ) ) #define BYTE_2( _x ) ( (uint8_t ) ( ( ( (uint32_t) (_x) ) >> 16 ) & 0xFF ) ) @@ -370,9 +496,36 @@ #endif + +#define _set_array_bit( _n, _byte_array, _max_bytes ) \ +do \ +{ \ + int byte_idx = (_n) >> 3; \ + \ + if ( byte_idx < _max_bytes ) \ + _byte_array[byte_idx] |= ( 1 << ( (_n) & 0x07 ) ); \ + \ +} while ( 0 ) + + +#define _clear_array_bit( _n, _byte_array, _max_bytes ) \ +do \ +{ \ + int byte_idx = (_n) >> 3; \ + \ + if ( byte_idx < _max_bytes ) \ + _byte_array[byte_idx] &= ~( 1 << ( (_n) & 0x07 ) ); \ + \ +} while ( 0 ) + + + +#define _isdigit( _c ) ( (_c) >= '0' && (_c) <= '9' ) + + // A macro function which can safely be used without // side effects as a macro doing nothing. -// This is useful to define debug macros away in +// This is useful to define debug macros away in // release builds, etc. #if !defined( _nop_macro_fnc ) #define _nop_macro_fnc() do {} while (0) @@ -384,8 +537,9 @@ */ typedef struct { - ulong code; + long code; const char *name; + } MBG_CODE_NAME_TABLE_ENTRY; /** @@ -405,6 +559,148 @@ typedef struct #define _mbg_cn_table_end() { 0, NULL } + +/** + * @brief A timestamp with nanosecond resolution + * + * @note If the structure is to represent a negative value then both the + * fields nano_secs and secs have to be set to the negative values. + * Otherwise the sign of the represented number was ambiguous if either + * of the fields was accidentally 0, and only the other field was not 0. + * The macro ::_nano_time_negative should always be used to determine + * if the sign of the represented value is negative, or not. + * + * @note The secs field will roll over on 2038-01-19 03:14:07 + * if used for the number of seconds since 1970-01-01, just like + * 32 bit POSIX time_t. + * + * @see ::_nano_time_negative + * @see ::_nano_time_zero + * @see ::NANO_TIME_64 + */ +typedef struct nano_time_s +{ + // ATTENTION: + // This structure is and has has been used in public API calls for a long time, + // so even though the order of member fields is different than in NANO_TIME_64 + // this must *NOT* be changed, or API compatibility will get lost! + int32_t nano_secs; ///< [nanoseconds] + int32_t secs; ///< [seconds], usually since 1970-01-01 00:00:00 + +} NANO_TIME; + +#define _mbg_swab_nano_time( _p ) \ +do \ +{ \ + _mbg_swab32( &(_p)->nano_secs ); \ + _mbg_swab32( &(_p)->secs ); \ +} while ( 0 ) + +/** + * Check if the value of the ::NANO_TIME structure _nt is negative + */ +#define _nano_time_negative( _nt ) \ + ( ( (_nt)->secs < 0 ) || ( (_nt)->nano_secs < 0 ) ) + +/** + * Check if the value of the ::NANO_TIME structure _nt is 0 + */ +#define _nano_time_zero( _nt ) \ + ( ( (_nt)->secs == 0 ) && ( (_nt)->nano_secs == 0 ) ) + + + +/** + * @brief A timestamp with nanosecond resolution, but 64 bit size + * + * @note If the structure is to represent a negative value then both the + * fields nano_secs and secs have to be set to the negative values. + * Otherwise the sign of the represented number was ambiguous if either + * of the fields was accidentally 0, and only the other field was not 0. + * The macro ::_nano_time_64_negative should always be used to determine + * if the sign of the represented value is negative, or not. + * + * @see ::_nano_time_64_negative + * @see ::_nano_time_64_zero + * @see ::NANO_TIME + */ +typedef struct nano_time_64_s +{ + // ATTENTION: + // This structure is and has been used in public API calls for a long time, + // so even though the order of member fields is different than in NANO_TIME + // this must *NOT* be changed, or API compatibility will get lost! + int64_t secs; ///< [seconds], usually since 1970-01-01 00:00:00 + int64_t nano_secs; ///< [nanoseconds] + +} NANO_TIME_64; + +#define _mbg_swab_nano_time_64( _p ) \ +do \ +{ \ + _mbg_swab64( &(_p)->secs ); \ + _mbg_swab64( &(_p)->nano_secs ); \ +} while ( 0 ) + +/** + * Check if the value of the ::NANO_TIME_64 structure _nt is negative + */ +#define _nano_time_64_negative( _nt ) \ + ( ( (_nt)->secs < 0 ) || ( (_nt)->nano_secs < 0 ) ) + +/** + * Check if the value of the ::NANO_TIME_64 structure _nt is 0 + */ +#define _nano_time_64_zero( _nt ) \ + ( ( (_nt)->secs == 0 ) && ( (_nt)->nano_secs == 0 ) ) + + + +// The size_t type can eventually be larger than an int type. +// However, some snprintf-like functions expect a size_t value +// to specify the buffer size, but just return an int value. +// So we take care that at least the return value is limited +// to MAXINT. +#if defined( MBG_TGT_WIN32 ) + #define _int_from_size_t( _n ) \ + ( ( (_n) > INT_MAX ) ? INT_MAX : (int) (_n) ) +#else + #define _int_from_size_t( _n ) (_n) +#endif + + + +/** + * @brief A helper macro to implement ::STRINGIFY correctly + * + * This just a helper macro which must be defined before + * ::STRINGIFY to work correctly, and should not be used alone. + * + * @see ::STRINGIFY + */ +#define XSTRINGIFY(x) #x + + +/** + * @brief Make a string from a constant definition + * + * This macro can be used e.g. to define a constant string on the + * compiler's command line, e.g. like -DVERSION_STRING="v1.0 BETA". + * Source code like + * @code{.c} + const char version_string[] = VERSION_STRING; + * @endcode + * + * may not work for every compiler since the double quotes + * in VERSION_STRING may be removed when the definition is evaluated. + * A proper solution is to use the STRINGIFY() macro defined here: + * @code{.c} + const char version_string[] = STRINGIFY( VERSION_STRING ); + * @endcode + */ +#define STRINGIFY(x) XSTRINGIFY(x) + + /* End of header body */ #undef _ext diff --git a/c/mbglib/lib/bc/mbgdevio.lib b/c/mbglib/lib/bc/mbgdevio.lib Binary files differindex e45f718..0abc3d1 100644 --- a/c/mbglib/lib/bc/mbgdevio.lib +++ b/c/mbglib/lib/bc/mbgdevio.lib diff --git a/c/mbglib/lib/bc/mbgsvcio.lib b/c/mbglib/lib/bc/mbgsvcio.lib Binary files differindex 86b966f..14263eb 100644 --- a/c/mbglib/lib/bc/mbgsvcio.lib +++ b/c/mbglib/lib/bc/mbgsvcio.lib diff --git a/c/mbglib/lib/bc/mbgsvctl.lib b/c/mbglib/lib/bc/mbgsvctl.lib Binary files differnew file mode 100644 index 0000000..136d929 --- /dev/null +++ b/c/mbglib/lib/bc/mbgsvctl.lib diff --git a/c/mbglib/lib/msc/mbgdevio.lib b/c/mbglib/lib/msc/mbgdevio.lib Binary files differindex d273251..ea9ea71 100644 --- a/c/mbglib/lib/msc/mbgdevio.lib +++ b/c/mbglib/lib/msc/mbgdevio.lib diff --git a/c/mbglib/lib/msc/mbgsvcio.lib b/c/mbglib/lib/msc/mbgsvcio.lib Binary files differindex c4987be..798b83f 100644 --- a/c/mbglib/lib/msc/mbgsvcio.lib +++ b/c/mbglib/lib/msc/mbgsvcio.lib diff --git a/c/mbglib/lib/msc/mbgsvctl.lib b/c/mbglib/lib/msc/mbgsvctl.lib Binary files differindex 0a2f61d..17ba8b7 100644 --- a/c/mbglib/lib/msc/mbgsvctl.lib +++ b/c/mbglib/lib/msc/mbgsvctl.lib diff --git a/c/mbglib/lib/msc/mbgutil.lib b/c/mbglib/lib/msc/mbgutil.lib Binary files differindex fe570bc..fb79fe5 100644 --- a/c/mbglib/lib/msc/mbgutil.lib +++ b/c/mbglib/lib/msc/mbgutil.lib diff --git a/c/mbglib/lib64/msc/mbgdevio.lib b/c/mbglib/lib64/msc/mbgdevio.lib Binary files differindex 8e443b7..7da95fc 100644 --- a/c/mbglib/lib64/msc/mbgdevio.lib +++ b/c/mbglib/lib64/msc/mbgdevio.lib diff --git a/c/mbglib/lib64/msc/mbgsvcio.lib b/c/mbglib/lib64/msc/mbgsvcio.lib Binary files differindex e9c4cd6..125e2df 100644 --- a/c/mbglib/lib64/msc/mbgsvcio.lib +++ b/c/mbglib/lib64/msc/mbgsvcio.lib diff --git a/c/mbglib/lib64/msc/mbgsvctl.lib b/c/mbglib/lib64/msc/mbgsvctl.lib Binary files differnew file mode 100644 index 0000000..6f09705 --- /dev/null +++ b/c/mbglib/lib64/msc/mbgsvctl.lib diff --git a/c/mbglib/lib64/msc/mbgutil.lib b/c/mbglib/lib64/msc/mbgutil.lib Binary files differindex 82ea1e1..56f0a0d 100644 --- a/c/mbglib/lib64/msc/mbgutil.lib +++ b/c/mbglib/lib64/msc/mbgutil.lib diff --git a/c/mbglib/win32/wingetopt.c b/c/mbglib/win32/wingetopt.c new file mode 100644 index 0000000..f7c7d7d --- /dev/null +++ b/c/mbglib/win32/wingetopt.c @@ -0,0 +1,90 @@ +/* +POSIX getopt for Windows + +AT&T Public License + +Code given out at the 1985 UNIFORUM conference in Dallas. +*/ + +#ifndef __GNUC__ + +#include "wingetopt.h" +#include <stdio.h> + +#if !defined( NULL ) + #define NULL 0 +#endif + +#if 1 //##++ defined( MSVC ) + + #include <string.h> + +// #define strcmp _strcmp +// #define strchr _strchr + +#endif + + +#define EOF (-1) +#define ERR(s, c) if(opterr){\ + char errbuf[2];\ + errbuf[0] = c; errbuf[1] = '\n';\ + fputs(argv[0], stderr);\ + fputs(s, stderr);\ + fputc(c, stderr);\ + /* (void) write(2, argv[0], (unsigned)strlen(argv[0])); */ \ + /* (void) write(2, s, (unsigned)strlen(s)); */ \ + /* (void) write(2, errbuf, 2); */ } + +int opterr = 1; +int optind = 1; +int optopt; +char *optarg; + +int +getopt(argc, argv, opts) +int argc; +char **argv, *opts; +{ + static int sp = 1; + register int c; + register char *cp; + + if(sp == 1) + if(optind >= argc || + argv[optind][0] != '-' || argv[optind][1] == '\0') + return(EOF); + else if(strcmp(argv[optind], "--") == 0) { + optind++; + return(EOF); + } + optopt = c = argv[optind][sp]; + if(c == ':' || (cp=strchr(opts, c)) == NULL) { + ERR(": illegal option -- ", c); + if(argv[optind][++sp] == '\0') { + optind++; + sp = 1; + } + return('?'); + } + if(*++cp == ':') { + if(argv[optind][sp+1] != '\0') + optarg = &argv[optind++][sp+1]; + else if(++optind >= argc) { + ERR(": option requires an argument -- ", c); + sp = 1; + return('?'); + } else + optarg = argv[optind++]; + sp = 1; + } else { + if(argv[optind][++sp] == '\0') { + sp = 1; + optind++; + } + optarg = NULL; + } + return(c); +} + +#endif /* __GNUC__ */ |