1/**
2 * @file profile_container.h
3 * Container associating symbols and samples
4 *
5 * @remark Copyright 2002, 2003 OProfile authors
6 * @remark Read the file COPYING
7 *
8 * @author Philippe Elie
9 * @author John Levon
10 */
11
12#ifndef PROFILE_CONTAINER_H
13#define PROFILE_CONTAINER_H
14
15#include <string>
16#include <vector>
17
18#include "profile.h"
19#include "utility.h"
20#include "op_bfd.h"
21#include "sample_container.h"
22#include "symbol_container.h"
23#include "format_flags.h"
24#include "locate_images.h"
25
26class string_filter;
27class symbol_entry;
28class sample_entry;
29
30/**
31 * Store multiple samples files belonging to the same profiling session.
32 * This is the main container capable of holding the profiles for arbitrary
33 * binary images and arbitrary profile classes.
34 */
35class profile_container : noncopyable {
36public:
37	/**
38	 * Build an object to store information on samples. All parameters
39	 * acts as hint for what you will request after recording samples and
40	 * so allow optimizations during recording the information.
41	 *
42	 * @param debug_info If true line numbers and source files are
43	 * recorded.
44	 * @param need_details If true if we need to record all samples or to
45	 * to record them at symbol level.
46	 * @param extra extra images location
47	 */
48	profile_container(bool debug_info, bool need_details,
49			  extra_images const & extra);
50
51	~profile_container();
52
53	/**
54	 * add() - record symbols/samples in the underlying container
55	 *
56	 * @param profile the samples files container
57	 * @param abfd the associated bfd object
58	 * @param app_name the owning application name of sample
59	 * @param pclass the profile class to add results for
60	 *
61	 * add() is an helper for delayed ctor. Take care you can't safely
62	 * make any call to add after any other member function call.
63	 * Obviously you can add only samples files which are coherent (same
64	 * sampling rate, same events etc.)
65	 */
66	void add(profile_t const & profile, op_bfd const & abfd,
67		 std::string const & app_name, size_t pclass);
68
69	/// Find a symbol from its image_name, vma, return zero if no symbol
70	/// for this image at this vma
71	symbol_entry const * find_symbol(std::string const & image_name,
72					 bfd_vma vma) const;
73
74	/// Find the symbols from its filename, linenr, return an empty
75	/// symbol_collection if no symbol at this location
76	symbol_collection const find_symbol(debug_name_id filename,
77					size_t linenr) const;
78
79	/// Find a sample by its symbol, vma, return zero if there is no sample
80	/// at this vma
81	sample_entry const * find_sample(symbol_entry const * symbol,
82					 bfd_vma vma) const;
83
84	/// Find a symbol. Return NULL if not found.
85	symbol_entry const * find(symbol_entry const & symbol) const;
86
87	/// used for select_symbols()
88	struct symbol_choice {
89		symbol_choice()
90			: hints(cf_none), threshold(0.0), match_image(false) {}
91
92		/// hints filled in
93		column_flags hints;
94		/// percentage threshold
95		double threshold;
96		/// match the image name only
97		bool match_image;
98		/// owning image name
99		std::string image_name;
100	};
101
102	/**
103	 * select_symbols - create a set of symbols sorted by sample count
104	 * @param choice  parameters to use/fill in when selecting
105	 */
106	symbol_collection const select_symbols(symbol_choice & choice) const;
107
108	/**
109	 * select_symbols - create a set of symbols belonging to a given source
110	 * @param filename  source file where are defined the returned symbols
111	 */
112	symbol_collection const select_symbols(debug_name_id filename) const;
113
114	/// Like select_symbols for filename without allowing sort by vma.
115	std::vector<debug_name_id> const select_filename(double threshold) const;
116
117	/// return the total number of samples
118	count_array_t samples_count() const;
119
120	/// Get the samples count which belongs to filename. Return 0 if
121	/// no samples found.
122	count_array_t samples_count(debug_name_id filename_id) const;
123	/// Get the samples count which belongs to filename, linenr. Return
124	/// 0 if no samples found.
125	count_array_t samples_count(debug_name_id filename,
126			   size_t linenr) const;
127
128	/// return an iterator to the first symbol
129	symbol_container::symbols_t::iterator begin_symbol() const;
130	/// return an iterator to the last symbol
131	symbol_container::symbols_t::iterator end_symbol() const;
132
133	/// return iterator to the first samples
134	sample_container::samples_iterator begin() const;
135	/// return iterator to the last samples
136	sample_container::samples_iterator end() const;
137
138	/// return iterator to the first samples for this symbol
139	sample_container::samples_iterator begin(symbol_entry const *) const;
140	/// return iterator to the last samples for this symbol
141	sample_container::samples_iterator end(symbol_entry const *) const;
142
143private:
144	/// helper for add()
145	void add_samples(op_bfd const & abfd, symbol_index_t sym_index,
146	                 profile_t::iterator_pair const &,
147	                 symbol_entry const * symbol, size_t pclass,
148			 unsigned long start);
149
150	/**
151	 * create an unique artificial symbol for an offset range. The range
152	 * is only a hint of the maximum size of the created symbol. We
153	 * give to the symbol an unique name as ?image_file_name#order and
154	 * a range up to the nearest of syms or for the whole range if no
155	 * syms exist after the start offset. the end parameter is updated
156	 * to reflect the symbol range.
157	 *
158	 * The rationale here is to try to create symbols for alignment between
159	 * function as little as possible and to create meaningfull symbols
160	 * for special case such image w/o symbol.
161	 */
162	std::string create_artificial_symbol(op_bfd const & abfd, u32 start,
163	                                     u32 & end, size_t & order);
164
165	/// The symbols collected by pp tools sorted by increased vma, provide
166	/// also a sort order on samples count for each profile class
167	scoped_ptr<symbol_container> symbols;
168	/// The samples count collected by pp tools sorted by increased vma,
169	/// provide also a sort order on (filename, linenr)
170	scoped_ptr<sample_container> samples;
171	/// build() must count samples count for each profile class so cache it
172	/// here since user of profile_container often need it later.
173	count_array_t total_count;
174
175	/**
176	 * Optimization hints for what information we are going to need,
177	 * see the explanation in profile_container()
178	 */
179	//@{
180	bool debug_info;
181	bool need_details;
182	//@}
183
184public: // FIXME
185	extra_images extra_found_images;
186};
187
188#endif /* !PROFILE_CONTAINER_H */
189