contrib/processor-trace/libipt/internal/include/pt_image.h

   1 /*
   2  * Copyright (c) 2013-2018, Intel Corporation
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   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.
  15  *
  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.
  27  */
  28
  29 #ifndef PT_IMAGE_H
  30 #define PT_IMAGE_H
  31
  32 #include "pt_mapped_section.h"
  33
  34 #include "intel-pt.h"
  35
  36 #include <stdint.h>
  37
  38
  39 /* A list of sections. */
  40 struct pt_section_list {
  41         /* The next list element. */
  42         struct pt_section_list *next;
  43
  44         /* The mapped section. */
  45         struct pt_mapped_section section;
  46
  47         /* The image section identifier. */
  48         int isid;
  49 };
  50
  51 /* A traced image consisting of a collection of sections. */
  52 struct pt_image {
  53         /* The optional image name. */
  54         char *name;
  55
  56         /* The list of sections. */
  57         struct pt_section_list *sections;
  58
  59         /* An optional read memory callback. */
  60         struct {
  61                 /* The callback function. */
  62                 read_memory_callback_t *callback;
  63
  64                 /* The callback context. */
  65                 void *context;
  66         } readmem;
  67 };
  68
  69 /* Initialize an image with an optional @name. */
  70 extern void pt_image_init(struct pt_image *image, const char *name);
  71
  72 /* Finalize an image.
  73  *
  74  * This removes all sections and frees the name.
  75  */
  76 extern void pt_image_fini(struct pt_image *image);
  77
  78 /* Add a section to an image.
  79  *
  80  * Add @section identified by @isid to @image at @vaddr in @asid.  If @section
  81  * overlaps with existing sections, the existing sections are shrunk, split, or
  82  * removed to accomodate @section.  Absence of a section identifier is indicated
  83  * by an @isid of zero.
  84  *
  85  * Returns zero on success.
  86  * Returns -pte_internal if @image, @section, or @asid is NULL.
  87  */
  88 extern int pt_image_add(struct pt_image *image, struct pt_section *section,
  89                         const struct pt_asid *asid, uint64_t vaddr, int isid);
  90
  91 /* Remove a section from an image.
  92  *
  93  * Returns zero on success.
  94  * Returns -pte_internal if @image, @section, or @asid is NULL.
  95  * Returns -pte_bad_image if @image does not contain @section at @vaddr.
  96  */
  97 extern int pt_image_remove(struct pt_image *image, struct pt_section *section,
  98                            const struct pt_asid *asid, uint64_t vaddr);
  99
 100 /* Read memory from an image.
 101  *
 102  * Reads at most @size bytes from @image at @addr in @asid into @buffer.
 103  *
 104  * Returns the number of bytes read on success, a negative error code otherwise.
 105  * Returns -pte_internal if @image, @isid, @buffer, or @asid is NULL.
 106  * Returns -pte_nomap if the section does not contain @addr.
 107  */
 108 extern int pt_image_read(struct pt_image *image, int *isid, uint8_t *buffer,
 109                          uint16_t size, const struct pt_asid *asid,
 110                          uint64_t addr);
 111
 112 /* Find an image section.
 113  *
 114  * Find the section containing @vaddr in @asid and provide it in @msec.  On
 115  * success, takes a reference of @msec->section that the caller needs to put
 116  * after use.
 117  *
 118  * Returns the section's identifier on success, a negative error code otherwise.
 119  * Returns -pte_internal if @image, @msec, or @asid is NULL.
 120  * Returns -pte_nomap if there is no such section in @image.
 121  */
 122 extern int pt_image_find(struct pt_image *image, struct pt_mapped_section *msec,
 123                          const struct pt_asid *asid, uint64_t vaddr);
 124
 125 /* Validate an image section.
 126  *
 127  * Validate that a lookup of @vaddr in @msec->asid in @image would result in
 128  * @msec identified by @isid.
 129  *
 130  * Validation may fail sporadically.
 131  *
 132  * Returns zero on success, a negative error code otherwise.
 133  * Returns -pte_invalid if @image or @msec is NULL.
 134  * Returns -pte_nomap if validation failed.
 135  */
 136 extern int pt_image_validate(const struct pt_image *image,
 137                              const struct pt_mapped_section *msec,
 138                              uint64_t vaddr, int isid);
 139
 140 #endif /* PT_IMAGE_H */