2 * Copyright (c) 2016-2018, Intel Corporation
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
7 * * Redistributions of source code must retain the above copyright notice,
8 * this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright notice,
10 * this list of conditions and the following disclaimer in the documentation
11 * and/or other materials provided with the distribution.
12 * * Neither the name of Intel Corporation nor the names of its contributors
13 * may be used to endorse or promote products derived from this software
14 * without specific prior written permission.
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
29 #ifndef PT_BLOCK_CACHE_H
30 #define PT_BLOCK_CACHE_H
37 /* A block cache entry qualifier.
39 * This describes what to do at the decision point determined by a block cache
42 enum pt_bcache_qualifier {
43 /* This is not a decision point.
45 * The next decision point is too far away and one or more fields
46 * threatened to overflow so we had to stop somewhere on our way.
48 * Apply the displacement and number of instructions and continue from
53 /* The decision point is a conditional branch.
55 * This requires a conditional branch query.
57 * The isize field should provide the size of the branch instruction so
58 * only taken branches require the instruction to be decoded.
62 /* The decision point is a near indirect call.
64 * This requires a return-address stack update and an indirect branch
67 * The isize field should provide the size of the call instruction so
68 * the return address can be computed by adding it to the displacement
69 * that brings us to the call instruction.
71 * No instruction decode is required.
75 /* The decision point is a near return.
77 * The return may be compressed so this requires a conditional branch
78 * query to determine the compression state and either a return-address
79 * stack lookup or an indirect branch query.
81 * No instruction decode is required.
85 /* The decision point is an indirect jump or far branch.
87 * This requires an indirect branch query.
89 * No instruction decode is required.
93 /* The decision point requires the instruction at the decision point IP
94 * to be decoded to determine the next step.
98 * - near direct calls that need to maintain the return-address stack.
100 * - near direct jumps that are too far away to be handled with a
101 * block cache entry as they would overflow the displacement field.
106 /* A block cache entry.
108 * There will be one such entry per byte of decoded memory image. Each entry
109 * corresponds to an IP in the traced memory image. The cache is initialized
110 * with invalid entries for all IPs.
112 * Only entries for the first byte of each instruction will be used; other
113 * entries are ignored and will remain invalid.
115 * Each valid entry gives the distance from the entry's IP to the next decision
116 * point both in bytes and in the number of instructions.
118 struct pt_bcache_entry {
119 /* The displacement to the next decision point in bytes.
121 * This is zero if we are at a decision point except for ptbq_again
122 * where it gives the displacement to the next block cache entry to be
125 int32_t displacement:16;
127 /* The number of instructions to the next decision point.
129 * This is typically one at a decision point since we are already
130 * accounting for the instruction at the decision point.
132 * Note that this field must be smaller than the respective struct
133 * pt_block field so we can fit one block cache entry into an empty
138 /* The execution mode for all instruction between here and the next
141 * This is enum pt_exec_mode.
143 * This is ptem_unknown if the entry is not valid.
147 /* The decision point qualifier.
149 * This is enum pt_bcache_qualifier.
151 uint32_t qualifier:3;
153 /* The size of the instruction at the decision point.
155 * This is zero if the size is too big to fit into the field. In this
156 * case, the instruction needs to be decoded to determine its size.
161 /* Get the execution mode of a block cache entry. */
162 static inline enum pt_exec_mode pt_bce_exec_mode(struct pt_bcache_entry bce)
164 return (enum pt_exec_mode) bce.mode;
167 /* Get the block cache qualifier of a block cache entry. */
168 static inline enum pt_bcache_qualifier
169 pt_bce_qualifier(struct pt_bcache_entry bce)
171 return (enum pt_bcache_qualifier) bce.qualifier;
174 /* Check if a block cache entry is valid. */
175 static inline int pt_bce_is_valid(struct pt_bcache_entry bce)
177 return pt_bce_exec_mode(bce) != ptem_unknown;
183 struct pt_block_cache {
184 /* The number of cache entries. */
187 /* A variable-length array of @nentries entries. */
188 struct pt_bcache_entry entry[];
191 /* Create a block cache.
193 * @nentries is the number of entries in the cache and should match the size of
194 * the to-be-cached section in bytes.
196 extern struct pt_block_cache *pt_bcache_alloc(uint64_t nentries);
198 /* Destroy a block cache. */
199 extern void pt_bcache_free(struct pt_block_cache *bcache);
203 * It is expected that all calls for the same @index write the same @bce.
205 * Returns zero on success, a negative error code otherwise.
206 * Returns -pte_internal if @bcache is NULL.
207 * Returns -pte_internal if @index is outside of @bcache.
209 extern int pt_bcache_add(struct pt_block_cache *bcache, uint64_t index,
210 struct pt_bcache_entry bce);
212 /* Lookup a cached block.
214 * The returned cache entry need not be valid. The caller is expected to check
215 * for validity using pt_bce_is_valid(*@bce).
217 * Returns zero on success, a negative error code otherwise.
218 * Returns -pte_internal if @bcache or @bce is NULL.
219 * Returns -pte_internal if @index is outside of @bcache.
221 extern int pt_bcache_lookup(struct pt_bcache_entry *bce,
222 const struct pt_block_cache *bcache,
225 #endif /* PT_BLOCK_CACHE_H */