op_events.h revision 84862f9f1c18e2906bd17871ed0970751de7eeae 
1/**
2 * @file op_events.h
3 * Details of PMC profiling events
4 *
5 * @remark Copyright 2002 OProfile authors
6 * @remark Read the file COPYING
7 *
8 * @author John Levon
9 * @author Philippe Elie
10 */
11
12#ifndef OP_EVENTS_H
13#define OP_EVENTS_H
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19#include "op_cpu_type.h"
20#include "op_types.h"
21#include "op_list.h"
22
23/** Describe an unit mask type. Events can optionally use a filter called
24 * the unit mask. the mask type can be a bitmask or a discrete value */
25enum unit_mask_type {
26	utm_mandatory,		/**< useless but required by the hardware */
27	utm_exclusive,		/**< only one of the values is allowed */
28	utm_bitmask		/**< bitmask */
29};
30
31/** up to thirty two allowed unit masks */
32#define MAX_UNIT_MASK 32
33
34
35/** Describe an unit mask. */
36struct op_unit_mask {
37	char * name;		/**< name of unit mask type */
38	u32 num;		/**< number of possible unit masks */
39	enum unit_mask_type unit_type_mask;
40	u32 default_mask;	/**< only the gui use it */
41	struct op_described_um {
42		u32 value;
43		char * desc;
44	} um[MAX_UNIT_MASK];
45	struct list_head um_next; /**< next um in list */
46	int used;                 /**< used by events file parser */
47};
48
49
50/** Describe an event. */
51struct op_event {
52	u32 counter_mask;	/**< bitmask of allowed counter  */
53	u32 val;		/**< event number */
54	/** which unit mask if any allowed */
55	struct op_unit_mask * unit;
56	char * name;		/**< the event name */
57	char * desc;      	/**< the event description */
58	int min_count;		/**< minimum counter value allowed */
59	int filter;		/**< architecture specific filter or -1 */
60	char * ext;		/**< extended events */
61	struct list_head event_next;   /**< next event in list */
62};
63
64/** Return the known events list. Idempotent */
65struct list_head * op_events(op_cpu cpu_type);
66
67/** Find a given event, returns NULL on error */
68struct op_event * op_find_event(op_cpu cpu_type, u32 nr, u32 um);
69struct op_event * op_find_event_any(op_cpu cpu_type, u32 nr);
70
71/** Find a given event by name */
72struct op_event * find_event_by_name(char const * name, unsigned um,
73                                     int um_valid);
74
75/**
76 * Find a mapping for a given event ID for architectures requiring additional information
77 * from what is held in the events file.
78 */
79char const * find_mapping_for_event(u32 val, op_cpu cpu_type);
80
81
82/** op_check_events() return code */
83enum op_event_check {
84	OP_OK_EVENT = 0, /**< event is valid and allowed */
85	OP_INVALID_EVENT = 1, /**< event number is invalid */
86	OP_INVALID_UM = 2, /**< unit mask is invalid */
87	OP_INVALID_COUNTER = 4 /**< event is not allowed for the given counter */
88};
89
90/**
91 * sanity check event values
92 * @param ctr counter number
93 * @param event value for counter
94 * @param um unit mask for counter
95 * @param cpu_type processor type
96 *
97 * Check that the counter event and unit mask values are allowed.
98 *
99 * The function returns bitmask of failure cause 0 otherwise
100 *
101 * \sa op_cpu, OP_EVENTS_OK
102 */
103int op_check_events(int ctr, u32 event, u32 um, op_cpu cpu_type);
104
105/**
106 * free memory used by any call to above function. Need to be called only once
107 */
108void op_free_events(void);
109
110struct op_default_event_descr {
111	char * name;
112	unsigned long count;
113	unsigned long um;
114};
115
116/**
117 * op_default_event - return the details of the default event
118 * @param cpu_type  cpu type
119 * @param descr filled event description
120 *
121 * Fills in the event description if applicable
122 */
123void op_default_event(op_cpu cpu_type, struct op_default_event_descr * descr);
124
125#ifdef __cplusplus
126}
127#endif
128
129#endif /* OP_EVENTS_H */
130