/*
 * This file and its contents are supplied under the terms of the
 * Common Development and Distribution License ("CDDL"), version 1.0.
 * You may only use this file in accordance with the terms of version
 * 1.0 of the CDDL.
 *
 * A full copy of the text of the CDDL should have accompanied this
 * source.  A copy of the CDDL is also available via the Internet at
 * http://www.illumos.org/license/CDDL.
 */

/*
 * Copyright 2020 Joyent, Inc.
 */

#ifndef _TSC_H
#define _TSC_H

#ifndef _ASM
#include <sys/linker_set.h>
#include <sys/types.h>
#endif

/*
 * flags to patch tsc_read routine.
 */
#define TSC_NONE                0x0
#define TSC_RDTSC_CPUID         0x1
/* formerly TSC_RDTSC_MFENCE    0x2 */
#define TSC_RDTSC_LFENCE        0x3
#define TSC_TSCP                0x4

#ifndef _ASM

/*
 * To register a TSC calibration source, a tsc_calibrate_t instance
 * should be created for the source, and then use
 * `TSC_CALIBRATION_SOURCE(<name_of_tsc_calibrate_t_instance_for_source>);`
 * to include it in the list of known sources.
 */
typedef struct tsc_calibrate {
        /*
         * A descriptive name for the source. While this is mostly for the
         * benefit of an operator, it may also be used to explicitly pick
         * a specific source (vs. trying sources in order of preference).
         * Each name should be unique (ignoring case).
         */
        const char      *tscc_source;

        /*
         * A preference value for this source. These values are largely
         * arbitrary and are just to impose an order the sequence of
         * sources to try (higher values of preference are tried before
         * lower values of preference).
         *
         * Typically, any hypervisor provided sources will be preferred
         * over hardware provided sources (i.e. cpuid), and higher precision
         * hardware counters will be preferred over lower precision counters
         * (e.g. HPET over PIT).
         */
        uint_t          tscc_preference;

        /*
         * The function that attempts calibration of the TSC. If the source
         * cannot calibrate the TSC for any reason (e.g. the calibration source
         * is not present or not supported on this machine), it should return
         * B_FALSE.
         *
         * If the source is successful in measuring the TSC frequency, it
         * should write the frequency of the TSC (in Hz) into the argument
         * passed, e.g.
         *
         * boolean_t
         * my_source(uint64_t *freq)
         * {
         *      ...
         *      *freq = measured_tsc_frequency;
         *      return (B_TRUE);
         * }
         *
         */
        boolean_t       (*tscc_calibrate)(uint64_t *);
} tsc_calibrate_t;
#define TSC_CALIBRATION_SOURCE(x) DATA_SET(tsc_calibration_set, x)

uint64_t tsc_calibrate(void);
uint64_t tsc_get_freq(void);

#endif /* _ASM */

#endif /* _TSC_H */