/*
 * Debug Store (DS) support
 *
 * This provides a low-level interface to the hardware's Debug Store
 * feature that is used for branch trace store (BTS) and
 * precise-event based sampling (PEBS).
 *
 * It manages:
 * - DS and BTS hardware configuration
 * - buffer overflow handling (to be done)
 * - buffer access
 *
 * It does not do:
 * - security checking (is the caller allowed to trace the task)
 * - buffer allocation (memory accounting)
 *
 *
 * Copyright (C) 2007-2009 Intel Corporation.
 * Markus Metzger <markus.t.metzger@intel.com>, 2007-2009
 */

#ifndef _ASM_X86_DS_H
#define _ASM_X86_DS_H


#include <linux/types.h>
#include <linux/init.h>
#include <linux/err.h>


#ifdef CONFIG_X86_DS

struct task_struct;
struct ds_context;
struct ds_tracer;
struct bts_tracer;
struct pebs_tracer;

typedef void (*bts_ovfl_callback_t)(struct bts_tracer *);
typedef void (*pebs_ovfl_callback_t)(struct pebs_tracer *);


/*
 * A list of features plus corresponding macros to talk about them in
 * the ds_request function's flags parameter.
 *
 * We use the enum to index an array of corresponding control bits;
 * we use the macro to index a flags bit-vector.
 */
enum ds_feature {
        dsf_bts = 0,
        dsf_bts_kernel,
#define BTS_KERNEL (1 << dsf_bts_kernel)
        /* trace kernel-mode branches */

        dsf_bts_user,
#define BTS_USER (1 << dsf_bts_user)
        /* trace user-mode branches */

        dsf_bts_overflow,
        dsf_bts_max,
        dsf_pebs = dsf_bts_max,

        dsf_pebs_max,
        dsf_ctl_max = dsf_pebs_max,
        dsf_bts_timestamps = dsf_ctl_max,
#define BTS_TIMESTAMPS (1 << dsf_bts_timestamps)
        /* add timestamps into BTS trace */

#define BTS_USER_FLAGS (BTS_KERNEL | BTS_USER | BTS_TIMESTAMPS)
};


/*
 * Request BTS or PEBS
 *
 * Due to alignement constraints, the actual buffer may be slightly
 * smaller than the requested or provided buffer.
 *
 * Returns a pointer to a tracer structure on success, or
 * ERR_PTR(errcode) on failure.
 *
 * The interrupt threshold is independent from the overflow callback
 * to allow users to use their own overflow interrupt handling mechanism.
 *
 * The function might sleep.
 *
 * task: the task to request recording for
 * cpu:  the cpu to request recording for
 * base: the base pointer for the (non-pageable) buffer;
 * size: the size of the provided buffer in bytes
 * ovfl: pointer to a function to be called on buffer overflow;
 *       NULL if cyclic buffer requested
 * th: the interrupt threshold in records from the end of the buffer;
 *     -1 if no interrupt threshold is requested.
 * flags: a bit-mask of the above flags
 */
extern struct bts_tracer *ds_request_bts_task(struct task_struct *task,
                                              void *base, size_t size,
                                              bts_ovfl_callback_t ovfl,
                                              size_t th, unsigned int flags);
extern struct bts_tracer *ds_request_bts_cpu(int cpu, void *base, size_t size,
                                             bts_ovfl_callback_t ovfl,
                                             size_t th, unsigned int flags);
extern struct pebs_tracer *ds_request_pebs_task(struct task_struct *task,
                                                void *base, size_t size,
                                                pebs_ovfl_callback_t ovfl,
                                                size_t th, unsigned int flags);
extern struct pebs_tracer *ds_request_pebs_cpu(int cpu,
                                               void *base, size_t size,
                                               pebs_ovfl_callback_t ovfl,
                                               size_t th, unsigned int flags);

/*
 * Release BTS or PEBS resources
 * Suspend and resume BTS or PEBS tracing
 *
 * Must be called with irq's enabled.
 *
 * tracer: the tracer handle returned from ds_request_~()
 */
extern void ds_release_bts(struct bts_tracer *tracer);
extern void ds_suspend_bts(struct bts_tracer *tracer);
extern void ds_resume_bts(struct bts_tracer *tracer);
extern void ds_release_pebs(struct pebs_tracer *tracer);
extern void ds_suspend_pebs(struct pebs_tracer *tracer);
extern void ds_resume_pebs(struct pebs_tracer *tracer);

/*
 * Release BTS or PEBS resources
 * Suspend and resume BTS or PEBS tracing
 *
 * Cpu tracers must call this on the traced cpu.
 * Task tracers must call ds_release_~_noirq() for themselves.
 *
 * May be called with irq's disabled.
 *
 * Returns 0 if successful;
 * -EPERM if the cpu tracer does not trace the current cpu.
 * -EPERM if the task tracer does not trace itself.
 *
 * tracer: the tracer handle returned from ds_request_~()
 */
extern int ds_release_bts_noirq(struct bts_tracer *tracer);
extern int ds_suspend_bts_noirq(struct bts_tracer *tracer);
extern int ds_resume_bts_noirq(struct bts_tracer *tracer);
extern int ds_release_pebs_noirq(struct pebs_tracer *tracer);
extern int ds_suspend_pebs_noirq(struct pebs_tracer *tracer);
extern int ds_resume_pebs_noirq(struct pebs_tracer *tracer);


/*
 * The raw DS buffer state as it is used for BTS and PEBS recording.
 *
 * This is the low-level, arch-dependent interface for working
 * directly on the raw trace data.
 */
struct ds_trace {
        /* the number of bts/pebs records */
        size_t n;
        /* the size of a bts/pebs record in bytes */
        size_t size;
        /* pointers into the raw buffer:
           - to the first entry */
        void *begin;
        /* - one beyond the last entry */
        void *end;
        /* - one beyond the newest entry */
        void *top;
        /* - the interrupt threshold */
        void *ith;
        /* flags given on ds_request() */
        unsigned int flags;
};

/*
 * An arch-independent view on branch trace data.
 */
enum bts_qualifier {
        bts_invalid,
#define BTS_INVALID bts_invalid

        bts_branch,
#define BTS_BRANCH bts_branch

        bts_task_arrives,
#define BTS_TASK_ARRIVES bts_task_arrives

        bts_task_departs,
#define BTS_TASK_DEPARTS bts_task_departs

        bts_qual_bit_size = 4,
        bts_qual_max = (1 << bts_qual_bit_size),
};

struct bts_struct {
        __u64 qualifier;
        union {
                /* BTS_BRANCH */
                struct {
                        __u64 from;
                        __u64 to;
                } lbr;
                /* BTS_TASK_ARRIVES or BTS_TASK_DEPARTS */
                struct {
                        __u64 clock;
                        pid_t pid;
                } event;
        } variant;
};


/*
 * The BTS state.
 *
 * This gives access to the raw DS state and adds functions to provide
 * an arch-independent view of the BTS data.
 */
struct bts_trace {
        struct ds_trace ds;

        int (*read)(struct bts_tracer *tracer, const void *at,
                    struct bts_struct *out);
        int (*write)(struct bts_tracer *tracer, const struct bts_struct *in);
};


/*
 * The PEBS state.
 *
 * This gives access to the raw DS state and the PEBS-specific counter
 * reset value.
 */
struct pebs_trace {
        struct ds_trace ds;

        /* the number of valid counters in the below array */
        unsigned int counters;

#define MAX_PEBS_COUNTERS 4
        /* the counter reset value */
        unsigned long long counter_reset[MAX_PEBS_COUNTERS];
};


/*
 * Read the BTS or PEBS trace.
 *
 * Returns a view on the trace collected for the parameter tracer.
 *
 * The view remains valid as long as the traced task is not running or
 * the tracer is suspended.
 * Writes into the trace buffer are not reflected.
 *
 * tracer: the tracer handle returned from ds_request_~()
 */
extern const struct bts_trace *ds_read_bts(struct bts_tracer *tracer);
extern const struct pebs_trace *ds_read_pebs(struct pebs_tracer *tracer);


/*
 * Reset the write pointer of the BTS/PEBS buffer.
 *
 * Returns 0 on success; -Eerrno on error
 *
 * tracer: the tracer handle returned from ds_request_~()
 */
extern int ds_reset_bts(struct bts_tracer *tracer);
extern int ds_reset_pebs(struct pebs_tracer *tracer);

/*
 * Set the PEBS counter reset value.
 *
 * Returns 0 on success; -Eerrno on error
 *
 * tracer: the tracer handle returned from ds_request_pebs()
 * counter: the index of the counter
 * value: the new counter reset value
 */
extern int ds_set_pebs_reset(struct pebs_tracer *tracer,
                             unsigned int counter, u64 value);

/*
 * Initialization
 */
struct cpuinfo_x86;
extern void __cpuinit ds_init_intel(struct cpuinfo_x86 *);

/*
 * Context switch work
 */
extern void ds_switch_to(struct task_struct *prev, struct task_struct *next);

#else /* CONFIG_X86_DS */

struct cpuinfo_x86;
static inline void __cpuinit ds_init_intel(struct cpuinfo_x86 *ignored) {}
static inline void ds_switch_to(struct task_struct *prev,
                                struct task_struct *next) {}

#endif /* CONFIG_X86_DS */
#endif /* _ASM_X86_DS_H */