/*

 * Copyright (c) 2005-2007 Hewlett-Packard Development Company, L.P.

 *               Contributed by Stephane Eranian <eranian@hpl.hp.com>

 * 

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of version 2 of the GNU General Public

 * License as published by the Free Software Foundation.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA

 * 02111-1307 USA

 *

 * This file implements the sampling format to support Intel

 * Precise Event Based Sampling (PEBS) feature of Pentium 4

 * and other Netburst-based processors. Not to be used for

 * Intel Core-based processors.

 *

 * What is PEBS?

 * ------------

 *  This is a hardware feature to enhance sampling by providing

 *  better precision as to where a sample is taken. This avoids the

 *  typical skew in the instruction one can observe with any

 *  interrupt-based sampling technique.

 *

 *  PEBS also lowers sampling overhead significantly by having the

 *  processor store samples instead of the OS. PMU interrupt are only

 *  generated after multiple samples are written.

 *

 *  Another benefit of PEBS is that samples can be captured inside

 *  critical sections where interrupts are masked.

 *

 * How does it work?

 *  PEBS effectively implements a Hw buffer. The Os must pass a region

 *  of memory where samples are to be stored. The region can have any

 *  size. The OS must also specify the sampling period to reload. The PMU

 *  will interrupt when it reaches the end of the buffer or a specified

 *  threshold location inside the memory region.

 *

 *  The description of the buffer is stored in the Data Save Area (DS).

 *  The samples are stored sequentially in the buffer. The format of the

 *  buffer is fixed and specified in the PEBS documentation.  The sample

 *  format changes between 32-bit and 64-bit modes due to extended register

 *  file.

 *

 *  PEBS does not work when HyperThreading is enabled due to certain MSR

 *  being shared being to two threads.

 *

 *  What does the format do?

 *   It provides access to the PEBS feature for both 32-bit and 64-bit

 *   processors that support it.

 *

 *   The same code is used for both 32-bit and 64-bit modes, but different

 *   format names are used because the two modes are not compatible due to

 *   data model and register file differences. Similarly the public data

 *   structures describing the samples are different.

 *

 *   It is important to realize that the format provides a zero-copy environment

 *   for the samples, i.e,, the OS never touches the samples. Whatever the

 *   processor write is directly accessible to the user.

 *

 *   Parameters to the buffer can be passed via pfm_create_context() in

 *   the pfm_pebs_smpl_arg structure.

 *

 *   It is not possible to mix a 32-bit PEBS application on top of a 64-bit

 *   host kernel.

 */

#ifndef __PERFMON_PEBS_P4_SMPL_H__

#define __PERFMON_PEBS_P4_SMPL_H__ 1

#ifdef __cplusplus

extern "C" {

#endif

#include <perfmon/perfmon.h>

#ifdef __i386__

#define PFM_PEBS_P4_SMPL_NAME	"pebs32_p4"

#else

#define PFM_PEBS_P4_SMPL_NAME	"pebs64_p4"

#endif

/*

 * format specific parameters (passed at context creation)

 */

typedef struct {

	uint64_t	cnt_reset;	/* counter reset value */

	size_t		buf_size;	/* size of the buffer in bytes */

	size_t		intr_thres;	/* index of interrupt threshold entry */

	uint64_t	reserved[6];	/* for future use */

} pfm_pebs_p4_smpl_arg_t;

/*

 * DS Save Area as described in section 15.10.5

 */

typedef struct {

	unsigned long	bts_buf_base;

	unsigned long	bts_index;

	unsigned long	bts_abs_max;

	unsigned long	bts_intr_thres;

	unsigned long	pebs_buf_base;

	unsigned long	pebs_index;

	unsigned long	pebs_abs_max;

	unsigned long	pebs_intr_thres;

	uint64_t	pebs_cnt_reset;

} pfm_ds_area_p4_t; 

/*

 * This header is at the beginning of the sampling buffer returned to the user.

 *

 * Because of PEBS alignement constraints, the actual PEBS buffer area does

 * not necessarily begin right after the header. The hdr_start_offs must be

 * used to compute the first byte of the buffer. The offset is defined as

 * the number of bytes between the end of the header and the beginning of

 * the buffer. As such the formula is:

 * 	actual_buffer = (unsigned long)(hdr+1)+hdr->hdr_start_offs

 */

typedef struct {

	uint64_t		overflows;	/* #overflows for buffer */

	size_t			buf_size;	/* bytes in the buffer */

	size_t			start_offs;	/* actual buffer start offset */

	uint32_t		version;	/* smpl format version */

	uint32_t		reserved1;	/* for future use */

	uint64_t		reserved2[5];	/* for future use */

	pfm_ds_area_p4_t	ds;		/* DS management Area */

} pfm_pebs_p4_smpl_hdr_t;

/*

 * PEBS record format as for both 32-bit and 64-bit modes

 */

typedef struct {

	unsigned long eflags;

	unsigned long ip;

	unsigned long eax;

	unsigned long ebx;

	unsigned long ecx;

	unsigned long edx;

	unsigned long esi;

	unsigned long edi;

	unsigned long ebp;

	unsigned long esp;

#ifdef __x86_64__

	unsigned long r8;

	unsigned long r9;

	unsigned long r10;

	unsigned long r11;

	unsigned long r12;

	unsigned long r13;

	unsigned long r14;

	unsigned long r15;

#endif

} pfm_pebs_p4_smpl_entry_t;

#define PFM_PEBS_P4_SMPL_VERSION_MAJ 1U

#define PFM_PEBS_P4_SMPL_VERSION_MIN 0U

#define PFM_PEBS_P4_SMPL_VERSION (((PFM_PEBS_P4_SMPL_VERSION_MAJ&0xffff)<<16)|\

				   (PFM_PEBS_P4_SMPL_VERSION_MIN & 0xffff))

#ifdef __cplusplus

};

#endif

#endif /* __PERFMON_PEBS_P4_SMPL_H__ */