/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */
/*
 * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

/*
 * CPC Performance Counter Backend
 *
 * To utilize the performance counters on a given CPU, a pcbe (Performance
 * Counter Backend) must be implemented for that CPU.
 *
 * This file defines the API which the kernel CPC implementation will call into.
 *
 */

#ifndef _SYS_CPC_PCBE_H
#define _SYS_CPC_PCBE_H

#include <sys/inttypes.h>
#include <sys/cpc_impl.h>

#ifdef  __cplusplus
extern "C" {
#endif

/*
 * All PCBEs must use PCBE_VER_1.
 */
#define PCBE_VER_1      1

#define PCBE_IMPL_NAME_P4HT     "Pentium 4 with HyperThreading"

typedef struct __pcbe_ops {
        uint_t          pcbe_ver;
        uint_t          pcbe_caps;
        uint_t          (*pcbe_ncounters)(void);
        const char      *(*pcbe_impl_name)(void);
        const char      *(*pcbe_cpuref)(void);
        char            *(*pcbe_list_events)(uint_t picnum);
        char            *(*pcbe_list_attrs)(void);
        uint64_t        (*pcbe_event_coverage)(char *event);
        uint64_t        (*pcbe_overflow_bitmap)(void);
        int             (*pcbe_configure)(uint_t, char *, uint64_t, uint_t,
                                uint_t, kcpc_attr_t *, void **, void *);
        void            (*pcbe_program)(void *);
        void            (*pcbe_allstop)(void);
        void            (*pcbe_sample)(void *);
        void            (*pcbe_free)(void *);
} pcbe_ops_t;

extern pcbe_ops_t *pcbe_ops;

/*
 * uint_t pcbe_ver;
 *
 *      Must always be set to PCBE_VER_1.
 *
 * uint_t pcbe_caps;
 *
 *      Bitmask of capability flags which define the processor's capabilities:
 *              CPC_CAP_OVERFLOW_INTERRUPT:
 *                      This processor can generate an interrupt when a counter
 *                      overflows.
 *
 *              CPC_CAP_OVERFLOW_PRECISE:
 *                      When an overflow interrupt occurs, the backend can
 *                      determine programmatically exactly which counter
 *                      overflowed.
 *
 * uint_t (*pcbe_ncounters)(void);
 *
 *      Returns the number of counters on the processor.
 *
 * const char *(*pcbe_impl_name)(void);
 *
 *      Returns a pointer to a string which uniquely identifies the CPC
 *      capabilities of the processor.
 *
 * const char *(*pcbe_cpuref)(void);
 *
 *      Returns a pointer to a string which points to a reference manual of
 *      some sort which should be consulted to understand the performance
 *      counters.
 *
 * char *(*pcbe_list_events)(uint_t picnum);
 *
 *      Returns a pointer to a comma-separated list of events which the given
 *      counter number is capable of counting. picnum starts at 0 and goes as
 *      high as (ncounters - 1).
 *
 * char *(*pcbe_list_attrs)(void);
 *
 *      Returns a pointer to a comma-separated list of attribute names which
 *      the PCBE supports.
 *
 * uint64_t (*pcbe_event_coverage)(char *event);
 *
 *      Returns a bitmask indicating which counters are capable of counting the
 *      named event. Counter n is deemed capable if bit (1 << n) is turned on,
 *      where counters range from 0 to (ncounters - 1).
 *
 * uint64_t (*pcbe_overflow_bitmap)(void);
 *
 *      Called by the kernel when a performance counter interrupt is received.
 *      This routine must return a bitmap of counters indicating which ones have
 *      overflowed. If the platform cannot determine this, it must act as if
 *      _all_ of its counters have overflowed.
 *
 * int (*pcbe_configure)(uint_t picnum, char *event, uint64_t preset,
 *                              uint_t flags, uint_t nattrs, kcpc_attr_t *attrp,
 *                              void **configp, void *token);
 *
 *      Returns a pointer to a PCBE-private data structure which can later be
 *      used to program the indicated picnum according to the arguments.
 *      token may be passed to kcpc_next_config() in order to walk the list of
 *      configurations which will be programmed together.
 *
 * void (*pcbe_program)(void *token);
 *
 *      Collects all configurations which will be programmed together, via
 *      kcpc_next_config(), programs them onto the hardware, and starts the
 *      performance counters.
 *
 * void (*pcbe_allstop)(void);
 *
 *      Stops all hardware performance counters.
 *
 * void (*pcbe_sample)(void *token);
 *
 *      Samples the values in the performance couters and updates the locations
 *      returned by kcpc_next_config() with the delta since the last sample.
 *
 * void (*pcbe_free)(void *config);
 *
 *      Frees the given configuration.
 */

#ifdef  __cplusplus
}
#endif

#endif /* _SYS_CPC_PCBE_H */