toolutil.c File Reference

#include <toolutil.h>
#include <cfg_hlp.h>
#include <pcpsutil.h>
#include <timeutil.h>
#include <str_util.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>

Go to the source code of this file.

Macros
#define	_TOOLUTIL

Functions
static __mbg_inline double	delta_timestamps (const PCPS_TIME_STAMP *p_ts, const PCPS_TIME_STAMP *p_prv_ts)
	Compute the difference between two PCPS_TIME_STAMP values. More...
int	mbg_program_version_str (char *s, size_t max_len)
	Print the program version to a string buffer. More...
int	mbg_program_info_str (char *s, size_t max_len, const char *pname, int first_year, int last_year)
	Print some program info to a string buffer. More...
void	mbg_print_program_info (const char *pname, int first_year, int last_year)
	Print program info to console. More...
void	mbg_print_usage_intro (const char *pname, const char *info)
	Print usage intro to console. More...
void	mbg_print_opt_info (const char *opt_name, const char *opt_info)
	Print info on a single program option / argument. More...
void	mbg_print_help_options (void)
	Print info on common program help arguments. More...
void	mbg_print_device_options (void)
	Print common info on how to specify devices on the command line. More...
void	mbg_print_default_usage (const char *pname, const char *prog_info)
	Print program info and default usage information. More...
int	mbg_get_show_dev_info (MBG_DEV_HANDLE dh, const char *dev_name, PCPS_DEV *p_dev)
	Retrieve and print some common device info. More...
int	mbg_handle_device (MBG_DEV_HANDLE dh, const char *dev_name, MBG_DEV_HANDLER_FNC *fnc)
	Print device info and take some action on a specific device. More...
int	chk_get_num_devices (void)
	Get the number of devices actually present. More...
int	mbg_open_device_by_param (MBG_DEV_HANDLE *p_dh, const char *dev_param_str, int dev_idx, char *dev_name_buffer, size_t dev_name_buffer_size)
	Try to open a device using a parameter string or device index. More...
int	mbg_open_device_by_param_chk (MBG_DEV_HANDLE *p_dh, const char *dev_param_str, int dev_idx, char *dev_name_buffer, size_t dev_name_buffer_size)
	Try to open a device and print a message in case of error. More...
int	mbg_handle_devices (int argc, char *argv[], int optind, MBG_DEV_HANDLER_FNC *fnc, int chk_dev_flags)
	Main action handler that can be called by utility programs. More...
int	mbg_snprint_date_time (char *s, size_t max_len, const PCPS_TIME *p, int verbose)
	Print date and time from a PCPS_TIME structure to a string. More...
int	mbg_snprint_hr_tstamp (char *s, size_t max_len, const PCPS_TIME_STAMP *p, long utc_offs, int show_raw)
	Print date and time from a PCPS_TIME_STAMP structure to a string. More...
int	mbg_snprint_hr_time (char *s, size_t max_len, const PCPS_HR_TIME *p, int show_raw)
	Print date and time from a PCPS_HR_TIME structure to a string. More...
void	mbg_print_hr_timestamp (PCPS_TIME_STAMP *p_ts, int32_t hns_latency, PCPS_TIME_STAMP *p_prv_ts, int no_latency, int show_raw)
	Print date and time from a PCPS_TIME_STAMP structure. More...
void	mbg_print_hr_time (PCPS_HR_TIME *p_ht, int32_t hns_latency, PCPS_TIME_STAMP *p_prv_ts, int no_latency, int show_raw, int verbose)
	Print date and time from a PCPS_HR_TIME structure. More...
int	mbg_show_pzf_corr_info (MBG_DEV_HANDLE dh, int show_corr_step)
	Retrieve and print PZF correlation info for a device which supports this. More...
int	mbg_get_gps_gnss_mode_info_chk (MBG_DEV_HANDLE dh, MBG_GNSS_MODE_INFO *p)
	Retrieve a MBG_GNSS_MODE_INFO structure from a device. More...

Macro Definition Documentation

_TOOLUTIL

#define _TOOLUTIL

Definition at line 73 of file toolutil.c.

Function Documentation

chk_get_num_devices()

int chk_get_num_devices

(

void

)

Get the number of devices actually present.

Do a real search only when called for the first time.

Returns

The number of devices currently present.

Definition at line 442 of file toolutil.c.

References mbg_find_devices().

Referenced by mbg_handle_devices(), and mbg_open_device_by_param().

delta_timestamps()

static __mbg_inline double delta_timestamps ( const PCPS_TIME_STAMP *  p_ts, const PCPS_TIME_STAMP *  p_prv_ts  )

static

Compute the difference between two PCPS_TIME_STAMP values.

Parameters

[in]	p_ts	Pointer to the current time stamp.
[in]	p_prv_ts	Pointer to a previous time stamp.

Returns

The time difference as double, in microseconds.

Definition at line 113 of file toolutil.c.

References MBG_FRAC32_UNITS_PER_SEC.

Referenced by mbg_print_hr_time(), and mbg_print_hr_timestamp().

mbg_get_gps_gnss_mode_info_chk()

int mbg_get_gps_gnss_mode_info_chk	(	MBG_DEV_HANDLE	dh,
		MBG_GNSS_MODE_INFO *	p
	)

Retrieve a MBG_GNSS_MODE_INFO structure from a device.

Parameters

[in]	dh	Valid MBG_DEV_HANDLE handle to a Meinberg device.
[out]	p	Pointer to a MBG_GNSS_MODE_INFO structure to be filled up.

Returns

MBG_SUCCESS on success, else one of the MBG_ERROR_CODES

Definition at line 1032 of file toolutil.c.

References mbg_cond_err_msg(), and mbg_get_gps_gnss_mode_info().

mbg_get_show_dev_info()

int mbg_get_show_dev_info	(	MBG_DEV_HANDLE	dh,
		const char *	dev_name,
		PCPS_DEV *	p_dev
	)

Retrieve and print some common device info.

Parameters

[in]	dh	Valid MBG_DEV_HANDLE handle to a Meinberg device.
[in]	dev_name	A device name string to be printed
[out]	p_dev	Pointer to a device info structure to be read from the device

Returns

MBG_SUCCESS on success, else one of the MBG_ERROR_CODES

Definition at line 317 of file toolutil.c.

References _convert_asic_version_number, _pcps_asic_version_major, _pcps_asic_version_minor, _pcps_fw_has_20ms_bug, _pcps_fw_rev_num, _pcps_fw_rev_num_major, _pcps_fw_rev_num_minor, _pcps_has_asic_version, _pcps_irq_num, _pcps_sernum, _pcps_short_port_base, _pcps_type_name, chk_sw_rev_name(), mbg_cond_err_msg(), mbg_get_asic_version(), mbg_get_device_info(), mbg_rc_is_success, mbg_setup_receiver_info(), MBG_SUCCESS, SW_REV::name, PCPS_ASIC_STR_FMT, PCPS_FW_STR_FMT, str_empty, and RECEIVER_INFO::sw_rev.

Referenced by main(), and mbg_handle_device().

mbg_handle_device()

int mbg_handle_device	(	MBG_DEV_HANDLE	dh,
		const char *	dev_name,
		MBG_DEV_HANDLER_FNC *	fnc
	)

Print device info and take some action on a specific device.

Parameters

[in]	dh	Valid MBG_DEV_HANDLE handle to a Meinberg device.
[in]	dev_name	A device name string to be printed.
[in]	fnc	Pointer to a callback function that actually takes the action.

Returns

MBG_SUCCESS on success, else one of the MBG_ERROR_CODES

Definition at line 412 of file toolutil.c.

References mbg_close_device(), mbg_get_show_dev_info(), and mbg_rc_is_success.

Referenced by mbg_handle_devices().

mbg_handle_devices()

int mbg_handle_devices	(	int	argc,
		char *	argv[],
		int	optind,
		MBG_DEV_HANDLER_FNC *	fnc,
		int	chk_dev_flags
	)

Main action handler that can be called by utility programs.

This function checks the command line parameters passed to the program. Those which have not been evaluated before are interpreted as device specifiers.

Device specifiers can be device file names like "/dev/mbgclock0" on target platforms that support such device names, see MBG_DEV_FN, or device type names like "GPS180PEX" which can optionally have a serial number appended, like "GPS180PEX_029511026220", to be able to distinguish between several devices of the same type (see MBG_DEV_NAME), or just an index number as required for the mbg_open_device call.

For each of the specified devices the callback function fnc is called to take some specific action on the device.

If no device has been specified in the argument list then mbg_find_devices is called to set up a device list, and depending on whether CHK_DEV_ALL_DEVICES is set in chk_dev_flags the callback function fnc is either called for every device from the list, or only for the first one.

Parameters

[in]	argc	Number of parameters of the program argument list.
[in]	argv	Array of program argument strings.
[in]	optind	Number of the command line arguments that have already been handled.
[in]	fnc	Pointer to a callback function that actually takes an action on each specified device.
[in]	chk_dev_flags	Bit mask controlling the behavior of the function, see CHK_DEV_FLAGS

Returns

MBG_SUCCESS on success, else one of the MBG_ERROR_CODES

Definition at line 655 of file toolutil.c.

References CHK_DEV_ALL_DEVICES, CHK_DEV_WITHOUT_DEV, chk_get_num_devices(), MBG_ERR_NO_DEV, mbg_handle_device(), MBG_INVALID_DEV_HANDLE, mbg_open_device_by_param_chk(), mbg_rc_is_error, and mbg_rc_is_success.

Referenced by main().

mbg_open_device_by_param()

int mbg_open_device_by_param	(	MBG_DEV_HANDLE *	p_dh,
		const char *	dev_param_str,
		int	dev_idx,
		char *	dev_name_buffer,
		size_t	dev_name_buffer_size
	)

Try to open a device using a parameter string or device index.

Parameters

[out]	p_dh	Address of a device handle variable to be set on success.
[in]	dev_param_str	An optional device specification string. This can be: A device file name, if the operating system supports this. See MBG_DEV_FN. A device model name like "GPS180PEX", eventually with the serial number appended after an underscore, as in "GPS180PEX_029511026220". See MBG_DEV_NAME. A device index number as string, e.g "0" or "3". NULL, in which case dev_idx has to be a valid device index number.
[in]	dev_idx	A device index number which is used if dev_param_str is NULL.
[out]	dev_name_buffer	A string buffer to which a device name can be written, see MBG_DEV_FN.
[in]	dev_name_buffer_size	The size of the dev_name_buffer buffer

Returns

MBG_SUCCESS on success, else one of the MBG_ERROR_CODES

See also

mbg_open_device_by_param

Definition at line 479 of file toolutil.c.

References chk_get_num_devices(), mbg_dev_fn_base, mbg_dev_fn_from_dev_idx(), MBG_ERR_GENERIC, MBG_ERR_INV_PARM, MBG_ERR_NO_DEV, MBG_ERR_RANGE, mbg_get_last_error(), MBG_INVALID_DEV_HANDLE, MBG_MATCH_MODEL, mbg_open_device(), mbg_open_device_by_dev_fn(), mbg_open_device_by_name(), MBG_SUCCESS, and snprintf_safe().

Referenced by main(), and mbg_open_device_by_param_chk().

mbg_open_device_by_param_chk()

int mbg_open_device_by_param_chk	(	MBG_DEV_HANDLE *	p_dh,
		const char *	dev_param_str,
		int	dev_idx,
		char *	dev_name_buffer,
		size_t	dev_name_buffer_size
	)

Try to open a device and print a message in case of error.

Call mbg_open_device_by_param to try to open a device, and print an error message to stderr if the call fails.

Parameters

[out]	p_dh	Address of a device handle variable to be set on success.
[in]	dev_param_str	An optional device specification string. This can be: A device file name, if the operating system supports this. See MBG_DEV_FN. A device model name like "GPS180PEX", eventually with the serial number appended after an underscore, as in "GPS180PEX_029511026220". See MBG_DEV_NAME. A device index number as string, e.g "0" or "3". NULL, in which case dev_idx has to be a valid device index number.
[in]	dev_idx	A device index number which is used if dev_param_str is NULL.
[out]	dev_name_buffer	A string buffer to which a device name can be written, see MBG_DEV_FN.
[in]	dev_name_buffer_size	The size of the dev_name_buffer buffer

Returns

MBG_SUCCESS on success, else one of the MBG_ERROR_CODES

See also

mbg_open_device_by_param

Definition at line 596 of file toolutil.c.

References mbg_open_device_by_param(), mbg_rc_is_error, mbg_strerror(), and snprintf_safe().

Referenced by main(), and mbg_handle_devices().

mbg_print_default_usage()

void mbg_print_default_usage	(	const char *	pname,
		const char *	prog_info
	)

Print program info and default usage information.

Parameters

[in]	pname	The program name.
[in]	prog_info	An optional additional info string, may be NULL.

Definition at line 296 of file toolutil.c.

References mbg_print_device_options(), mbg_print_help_options(), and mbg_print_usage_intro().

mbg_print_device_options()

void mbg_print_device_options

(

void

)

Print common info on how to specify devices on the command line.

Definition at line 270 of file toolutil.c.

References EXAMPLE_DEV_FN_1, EXAMPLE_DEV_FN_2, EXAMPLE_DEV_NAME_1, and EXAMPLE_DEV_NAME_2.

Referenced by mbg_print_default_usage(), and usage().

mbg_print_help_options()

void mbg_print_help_options

(

void

)

Print info on common program help arguments.

Lists program parameters causing printing of help / usage information.

Definition at line 257 of file toolutil.c.

References mbg_print_opt_info().

Referenced by mbg_print_default_usage(), and usage().

mbg_print_hr_time()

void mbg_print_hr_time	(	PCPS_HR_TIME *	p_ht,
		int32_t	hns_latency,
		PCPS_TIME_STAMP *	p_prv_ts,
		int	no_latency,
		int	show_raw,
		int	verbose
	)

Print date and time from a PCPS_HR_TIME structure.

First the HR timestamp passed by parameter p_ht is printed.

If the parameter p_prv_ts is not NULL then it should specify an earlier timestamp, and the elapsed time since p_ht is appended.

Next the latency value is printed in microseconds, unless parameter no_latency is != 0.

Parameters

[in]	p_ht	Pointer to a PCPS_TIME_STAMP structure to be evaluated.
[in]	hns_latency	A latency number in hectonanoseconds, i.e. 100 ns units.
[in]	p_prv_ts	Pointer to a PCPS_TIME_STAMP structure to be evaluated, may be NULL
[in]	no_latency	A flag indicating if printing the latency should be suppressed.
[in]	show_raw	Flag indicating if a raw timestamp (hex) is to be printed, too.
[in]	verbose	Increase verbosity of the output: > 0: append status code > 1: append signal value

See also

mbg_print_hr_timestamp

Definition at line 956 of file toolutil.c.

References delta_timestamps(), mbg_snprint_hr_time(), PCPS_HR_TIME::signal, PCPS_HR_TIME::status, and PCPS_HR_TIME::tstamp.

Referenced by show_hr_timestamp(), and show_hr_timestamp_burst().

mbg_print_hr_timestamp()

void mbg_print_hr_timestamp	(	PCPS_TIME_STAMP *	p_ts,
		int32_t	hns_latency,
		PCPS_TIME_STAMP *	p_prv_ts,
		int	no_latency,
		int	show_raw
	)

Print date and time from a PCPS_TIME_STAMP structure.

First the HR timestamp passed by parameter p_ts is printed.

If the parameter p_prv_ts is not NULL then it should specify an earlier timestamp, and the elapsed time since p_ts is appended.

Finally the latency value is printed in microseconds, unless parameter no_latency is != 0.

Parameters

[in]	p_ts	Pointer to a PCPS_TIME_STAMP structure to be evaluated.
[in]	hns_latency	A latency number in hectonanoseconds, i.e. 100 ns units.
[in]	p_prv_ts	Pointer to a PCPS_TIME_STAMP structure to be evaluated, may be NULL
[in]	no_latency	A flag indicating if printing the latency should be suppressed.
[in]	show_raw	Flag indicating if a raw timestamp (hex) is to be printed, too.

See also

mbg_print_hr_time

Definition at line 912 of file toolutil.c.

References delta_timestamps(), mbg_snprint_hr_tstamp(), and str_empty.

Referenced by show_fast_hr_timestamp(), and show_fast_hr_timestamp_burst().

mbg_print_opt_info()

void mbg_print_opt_info	(	const char *	opt_name,
		const char *	opt_info
	)

Print info on a single program option / argument.

Parameters

[in]	opt_name	The option name, optional, may be NULL.
[in]	opt_info	The option info, optional, may be NULL.

Definition at line 236 of file toolutil.c.

References str_empty.

Referenced by mbg_print_help_options(), and usage().

mbg_print_program_info()

void mbg_print_program_info	(	const char *	pname,
		int	first_year,
		int	last_year
	)

Print program info to console.

Parameters

[in]	pname	The program name.
[in]	first_year	First copyright year.
[in]	last_year	Last copyright year.

Definition at line 193 of file toolutil.c.

References mbg_program_info_str().

Referenced by main().

mbg_print_usage_intro()

void mbg_print_usage_intro	(	const char *	pname,
		const char *	info
	)

Print usage intro to console.

Parameters

[in]	pname	The program name.
[in]	info	An optional additional info string, may be NULL.

Definition at line 217 of file toolutil.c.

Referenced by mbg_print_default_usage(), and usage().

mbg_program_info_str()

int mbg_program_info_str	(	char *	s,
		size_t	max_len,
		const char *	pname,
		int	first_year,
		int	last_year
	)

Print some program info to a string buffer.

Parameters

[out]	s	Address of a string buffer to be filled.
[in]	max_len	Size of the string buffer.
[in]	pname	The program name.
[in]	first_year	First copyright year.
[in]	last_year	Last copyright year.

Returns

The number of characters printed to the buffer.

Definition at line 160 of file toolutil.c.

References MBG_CURRENT_COPYRIGHT_YEAR, mbg_program_version_str(), and snprintf_safe().

Referenced by main(), and mbg_print_program_info().

mbg_program_version_str()

int mbg_program_version_str	(	char *	s,
		size_t	max_len
	)

Print the program version to a string buffer.

Parameters

[out]	s	Address of a string buffer to be filled.
[in]	max_len	Size of the string buffer.

Returns

The number of characters printed to the buffer.

Definition at line 135 of file toolutil.c.

References MBG_MAJOR_VERSION_CODE, MBG_MICRO_VERSION_CODE, MBG_MINOR_VERSION_CODE, and snprintf_safe().

Referenced by mbg_program_info_str().

mbg_show_pzf_corr_info()

int mbg_show_pzf_corr_info	(	MBG_DEV_HANDLE	dh,
		int	show_corr_step
	)

Retrieve and print PZF correlation info for a device which supports this.

Parameters

[in]	dh	Valid MBG_DEV_HANDLE handle to a Meinberg device.
[in]	show_corr_step	A flag indicating if correlation step indicators are to be appended

Returns

MBG_SUCCESS on success, else one of the MBG_ERROR_CODES

Definition at line 991 of file toolutil.c.

References CORR_INFO::corr_dir, mbg_cond_err_msg(), mbg_get_corr_info(), MBG_SUCCESS, N_PZF_CORR_STATE, pzf_corr_state_name, snprintf_safe(), CORR_INFO::status, and CORR_INFO::val.

Referenced by show_modulation(), and show_time_and_status().

mbg_snprint_date_time()

int mbg_snprint_date_time	(	char *	s,
		size_t	max_len,
		const PCPS_TIME *	p,
		int	verbose
	)

Print date and time from a PCPS_TIME structure to a string.

Parameters

[out]	s	Address of a string buffer to be filled.
[in]	max_len	Size of the string buffer.
[in]	p	Pointer to a PCPS_TIME structure to be evaluated.
[in]	verbose	Increase verbosity of the output: > 0: append UTC offset and status > 1: append signal value

Returns

The number of characters printed to the buffer.

Definition at line 766 of file toolutil.c.

References _int_from_size_t, PCPS_TIME::hour, mbg_exp_year_limit, PCPS_TIME::mday, PCPS_TIME::min, PCPS_TIME::month, PCPS_TIME::offs_utc, pcps_exp_year(), PCPS_TIME::sec, PCPS_TIME::sec100, PCPS_TIME::signal, snprintf_safe(), PCPS_TIME::status, and PCPS_TIME::year.

mbg_snprint_hr_time()

int mbg_snprint_hr_time	(	char *	s,
		size_t	max_len,
		const PCPS_HR_TIME *	p,
		int	show_raw
	)

Print date and time from a PCPS_HR_TIME structure to a string.

Converts the UTC timestamp first to local time according to the PCPS_HR_TIME::utc_offs value.

Parameters

[out]	s	Address of a string buffer to be filled.
[in]	max_len	Size of the string buffer.
[in]	p	Pointer to a PCPS_HR_TIME structure to be evaluated.
[in]	show_raw	Flag indicating if a raw timestamp (hex) is to be printed, too.

Returns

The number of characters printed to the buffer.

Definition at line 851 of file toolutil.c.

References _int_from_size_t, mbg_snprint_hr_tstamp(), PCPS_SCALE_GPS, PCPS_SCALE_TAI, snprint_utc_offs(), snprintf_safe(), PCPS_HR_TIME::status, PCPS_HR_TIME::tstamp, and PCPS_HR_TIME::utc_offs.

Referenced by do_mbgxhrtime(), mbg_print_hr_time(), show_time_and_status(), and show_ucap_event().

mbg_snprint_hr_tstamp()

int mbg_snprint_hr_tstamp	(	char *	s,
		size_t	max_len,
		const PCPS_TIME_STAMP *	p,
		long	utc_offs,
		int	show_raw
	)

Print date and time from a PCPS_TIME_STAMP structure to a string.

Parameters

[out]	s	Address of a string buffer to be filled.
[in]	max_len	Size of the string buffer.
[in]	p	Pointer to a PCPS_TIME_STAMP structure to be evaluated.
[in]	utc_offs	A local time offset added to the time stamp before converted to date and time.
[in]	show_raw	Flag indicating if a raw timestamp (hex) is to be printed, too.

Returns

The number of characters printed to the buffer.

Definition at line 799 of file toolutil.c.

References _int_from_size_t, bin_frac_32_to_dec_frac(), cvt_to_time_t(), PCPS_TIME_STAMP::frac, mbg_gmtime(), mbg_rc_is_success, PCPS_HRT_FRAC_SCALE, PCPS_HRT_FRAC_SCALE_FMT, PCPS_TIME_STAMP::sec, snprint_gmtime_error(), and snprintf_safe().

Referenced by mbg_print_hr_timestamp(), mbg_snprint_hr_time(), mbg_snprint_hr_time_loc(), mbg_snprint_hr_tstamp_ext(), set_event_time(), show_time_and_status(), and snprint_chk_time_info().