coregrind/m_debuginfo/priv_image.h

   1
   2 /*--------------------------------------------------------------------*/
   3 /*--- An abstraction that provides a file-reading mechanism.       ---*/
   4 /*---                                                 priv_image.h ---*/
   5 /*--------------------------------------------------------------------*/
   6
   7 /*
   8    This file is part of Valgrind, a dynamic binary instrumentation
   9    framework.
  10
  11    Copyright (C) 2013-2017 Mozilla Foundation
  12
  13    This program is free software; you can redistribute it and/or
  14    modify it under the terms of the GNU General Public License as
  15    published by the Free Software Foundation; either version 2 of the
  16    License, or (at your option) any later version.
  17
  18    This program is distributed in the hope that it will be useful, but
  19    WITHOUT ANY WARRANTY; without even the implied warranty of
  20    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21    General Public License for more details.
  22
  23    You should have received a copy of the GNU General Public License
  24    along with this program; if not, see <http://www.gnu.org/licenses/>.
  25
  26    The GNU General Public License is contained in the file COPYING.
  27 */
  28
  29 /* Contributed by Julian Seward <jseward@acm.org> */
  30
  31 #ifndef __PRIV_IMAGE_H
  32 #define __PRIV_IMAGE_H
  33
  34 #include "pub_core_basics.h"    // ULong
  35 #include "priv_misc.h"          // ML_(dinfo_zalloc)
  36
  37 /*------------------------------------------------------------*/
  38 /*--- DiImage -- abstract images                           ---*/
  39 /*------------------------------------------------------------*/
  40
  41 /* The basic type, containing an abstractified memory area that can be
  42    read from.  This is an abstract type since there can be more than
  43    one implementation of it. */
  44
  45 /* abstract */
  46 typedef  struct _DiImage  DiImage;
  47
  48 /* an offset in the image */
  49 typedef  ULong  DiOffT;
  50
  51 /* This denotes an invalid DiOffT value.  Except where otherwise
  52    noted, you must never pass this to any of the ML_(image_*)
  53    functions -- they will assert.  That does mean though that they can
  54    be used for signalling other conditions, for example that some
  55    expected part of the image is missing. */
  56 #define DiOffT_INVALID ((DiOffT)(0xFFFFFFFFFFFFFFFFULL))
  57
  58 /* Create an image from a file in the local filesysem.  Returns NULL
  59    if it fails, for whatever reason. */
  60 DiImage* ML_(img_from_local_file)(const HChar* fullpath);
  61
  62 DiImage* ML_(img_from_fd)(Int fd, const HChar* fullpath);
  63
  64 /* Create an image by connecting to a Valgrind debuginfo server
  65    (auxprogs/valgrind-di-server.c).  |filename| contains the object
  66    name to ask for; it must be a plain filename, not absolute, not a
  67    path.  |serverAddr| must be of the form either "d.d.d.d" or
  68    "d.d.d.d:d" where d is one or more digits.  These specify the IPv4
  69    address and (in the second case) port number for the server.  In
  70    the first case, port 1500 is assumed. */
  71 DiImage* ML_(img_from_di_server)(const HChar* filename,
  72                                  const HChar* serverAddr);
  73
  74 /* Free memory allocated for image. */
  75 void ML_(img_free)(DiImage*);
  76
  77 /* Destroy an existing image. */
  78 void ML_(img_done)(DiImage*);
  79
  80 /* Virtual size of the image. */
  81 DiOffT ML_(img_size)(const DiImage* img);
  82
  83 /* Real size of the image. */
  84 DiOffT ML_(img_real_size)(const DiImage* img);
  85
  86 /* Does the section [offset, +size) exist in the image? */
  87 Bool ML_(img_valid)(const DiImage* img, DiOffT offset, SizeT size);
  88
  89 /* Get info out of an image.  If any part of the section denoted by
  90    [offset, +size) is invalid, does not return. */
  91 void ML_(img_get)(/*OUT*/void* dst,
  92                   DiImage* img, DiOffT offset, SizeT size);
  93
  94 /* A version of ML_(img_get) that is significantly cheaper when
  95    fetching a lot of data, at the cost of being more difficult to use.
  96    Fetches between 1 and |size| bytes from |img| at |offset| and
  97    places them in |dst|.  |size| must be at least 1.  The number of
  98    bytes read is returned, and the caller must be able to deal with
  99    any number between 1 and |size|.  |offset| must be a valid offset
 100    in the image; if not the function will not return.  This function
 101    will not read off the end of the image. */
 102 SizeT ML_(img_get_some)(/*OUT*/void* dst,
 103                         DiImage* img, DiOffT offset, SizeT size);
 104
 105 /* Copy a C string out of the image, into ML_(dinfo_zalloc)'d space.
 106    The caller owns the string and must free it with ML_(dinfo_free).
 107    |offset| may be DiOffT_INVALID, in which case this returns NULL. */
 108 HChar* ML_(img_strdup)(DiImage* img, const HChar* cc, DiOffT offset);
 109
 110 /* Do strcmp on two C strings in the image.  Chars are cast to HChar
 111    before comparison. */
 112 Int ML_(img_strcmp)(DiImage* img, DiOffT off1, DiOffT off2);
 113
 114 /* Do strcmp of a C string in the image vs a normal one.  Chars are
 115    cast to HChar before comparison. */
 116 Int ML_(img_strcmp_c)(DiImage* img, DiOffT off1, const HChar* str2);
 117
 118 /* Do strlen of a C string in the image. */
 119 SizeT ML_(img_strlen)(DiImage* img, DiOffT off);
 120
 121 /* Fetch various sized primitive types from the image.  These operate
 122    at the endianness and word size of the host. */
 123 UChar  ML_(img_get_UChar) (DiImage* img, DiOffT offset);
 124 UShort ML_(img_get_UShort)(DiImage* img, DiOffT offset);
 125 UInt   ML_(img_get_UInt)  (DiImage* img, DiOffT offset);
 126 ULong  ML_(img_get_ULong) (DiImage* img, DiOffT offset);
 127
 128 /* Calculate the "GNU Debuglink CRC" for the image.  This
 129    unfortunately has to be done as part of the DiImage implementation
 130    because it involves reading the entire image, and is therefore
 131    something that needs to be handed off to the remote server -- since
 132    to do it otherwise would imply pulling the entire image across the
 133    connection, making the client/server split pointless. */
 134 UInt ML_(img_calc_gnu_debuglink_crc32)(DiImage* img);
 135
 136 /* Mark compressed part of image defined with (offset, szC).
 137    szD is length of uncompressed data (should be known before decompression).
 138    Returns (virtual) position in image from which decompressed data can be
 139    read. */
 140 DiOffT ML_(img_mark_compressed_part)(DiImage* img, DiOffT offset, SizeT szC,
 141                                      SizeT szD);
 142
 143
 144 /*------------------------------------------------------------*/
 145 /*--- DiCursor -- cursors for reading images               ---*/
 146 /*------------------------------------------------------------*/
 147
 148 /* A type built on DiImage.  It contains a DiImage and a 'current
 149    offset' in the image, and is useful for building low level readers
 150    of images.  In the functions section below, "read" means "read data
 151    at the cursor without moving it along", and "step" means "read data
 152    at the cursor and move it along by the size of the item read". */
 153 typedef
 154    struct { DiImage* img; DiOffT ioff; }
 155    DiCursor;
 156
 157 /* An invalid cursor.  You can't use it for anything. */
 158 #define DiCursor_INVALID ((DiCursor){NULL,DiOffT_INVALID})
 159
 160 static inline DiCursor mk_DiCursor ( DiImage* img, DiOffT ioff ) {
 161    return (DiCursor){img, ioff};
 162 }
 163
 164 static inline Bool ML_(cur_is_valid)(DiCursor c) {
 165    return c.img != NULL;
 166 }
 167
 168
 169 /*------------------------------------------------------------*/
 170 /*--- DiSlice -- subranges within DiImages                 ---*/
 171 /*------------------------------------------------------------*/
 172
 173 /* Another type built on top of DiImage.  It denotes a subrange of an
 174    image and is useful for representing (eg) exactly the part of an
 175    image that is a specific ELF section. */
 176 typedef
 177    struct { DiImage* img; DiOffT ioff; DiOffT szB; }
 178    DiSlice;
 179
 180 /* A DiSlice can also be INVALID, meaning it does not refer to any
 181    part of any image. */
 182 #define DiSlice_INVALID ((DiSlice){NULL,DiOffT_INVALID,0})
 183
 184 static inline DiSlice mk_DiSlice ( DiImage* img, DiOffT ioff, DiOffT szB ) {
 185    return (DiSlice){img, ioff, szB};
 186 }
 187
 188 static inline Bool ML_(sli_is_valid)( DiSlice sli ) {
 189    return sli.img != NULL;
 190 }
 191
 192 /* Create a slice from a combination of a cursor and a length.  The
 193    maximum implied offset must not exceed the size of the underlying
 194    image; this is asserted for. */
 195 static inline DiSlice ML_(sli_from_cur)( DiCursor cur, DiOffT size ) {
 196    if (ML_(cur_is_valid)(cur)) {
 197       vg_assert(size != DiOffT_INVALID);
 198       vg_assert(cur.ioff + size <= ML_(img_size)(cur.img));
 199       return mk_DiSlice(cur.img, cur.ioff, size);
 200    } else {
 201       return DiSlice_INVALID;
 202    }
 203 }
 204
 205 /* Create a slice which exactly covers the given image. */
 206 static inline DiSlice ML_(sli_from_img)( DiImage* img ) {
 207    if (img) {
 208       return mk_DiSlice(img, 0, ML_(img_size)(img));
 209    } else {
 210       return DiSlice_INVALID;
 211    }
 212 }
 213
 214
 215 /*------------------------------------------------------------*/
 216 /*--- Functions that operate on DiCursors                  ---*/
 217 /*------------------------------------------------------------*/
 218
 219 /* Create a cursor from a slice, referring to the first byte of the
 220    slice. */
 221 static inline DiCursor ML_(cur_from_sli)( DiSlice sl ) {
 222    if (ML_(sli_is_valid)(sl)) {
 223       DiCursor c;
 224       c.img  = sl.img;
 225       c.ioff = sl.ioff;
 226       return c;
 227    } else {
 228       return DiCursor_INVALID;
 229    }
 230 }
 231
 232 static inline Bool ML_(cur_cmpLT)( DiCursor c1, DiCursor c2 ) {
 233    vg_assert(c1.img == c2.img);
 234    return c1.ioff < c2.ioff;
 235 }
 236 static inline Bool ML_(cur_cmpEQ)( DiCursor c1, DiCursor c2 ) {
 237    vg_assert(c1.img == c2.img);
 238    return c1.ioff == c2.ioff;
 239 }
 240 static inline Bool ML_(cur_cmpGT)( DiCursor c1, DiCursor c2 ) {
 241    vg_assert(c1.img == c2.img);
 242    return c1.ioff > c2.ioff;
 243 }
 244
 245 static inline DiCursor ML_(cur_plus)( DiCursor c, Long n ) {
 246    c.ioff += (DiOffT)n;
 247    return c;
 248 }
 249
 250 /* Asserts that c1 and c2 refer to the same image.  Returns the difference
 251    in offsets (c1.ioff - c2.ioff). */
 252 static inline Long ML_(cur_minus)( DiCursor c1, DiCursor c2 ) {
 253    vg_assert(c1.img == c2.img);
 254    return (Long)(c1.ioff) - (Long)(c2.ioff);
 255 }
 256
 257 static inline SizeT ML_(cur_strlen)( DiCursor c ) {
 258    return ML_(img_strlen)( c.img, c.ioff );
 259 }
 260
 261 // strdup from the given cursor.  Caller must ML_(dinfo_free) the
 262 // resulting string.
 263 static inline HChar* ML_(cur_read_strdup)( DiCursor c, const HChar* cc ) {
 264    vg_assert(c.ioff != DiOffT_INVALID);
 265    HChar* res = ML_(img_strdup)(c.img, cc, c.ioff);
 266    return res;
 267 }
 268 // strdup from the given cursor and advance it.  Caller must
 269 // ML_(dinfo_free) the resulting string.
 270 static inline HChar* ML_(cur_step_strdup)( DiCursor* c, const HChar* cc ) {
 271    vg_assert(c->ioff != DiOffT_INVALID);
 272    HChar* res = ML_(img_strdup)(c->img, cc, c->ioff);
 273    c->ioff += VG_(strlen)(res) + 1;
 274    return res;
 275 }
 276
 277 // Fetch an arbitrary number of bytes from the cursor.
 278 static inline void ML_(cur_read_get) ( /*OUT*/void* dst,
 279                                        DiCursor c, SizeT size) {
 280    ML_(img_get)(dst, c.img, c.ioff, size);
 281 }
 282
 283 // Fetch an arbitrary number of bytes from the cursor, and advance it.
 284 static inline void ML_(cur_step_get) ( /*OUT*/void* dst,
 285                                        DiCursor* c, SizeT size) {
 286    ML_(img_get)(dst, c->img, c->ioff, size);
 287    c->ioff += size;
 288 }
 289
 290 // memdup from the given cursor.  Caller must ML_(dinfo_free) the
 291 // resulting block.
 292 static inline UChar* ML_(cur_read_memdup)( DiCursor c, SizeT size,
 293                                            const HChar* cc )
 294 {
 295    UChar* dst = ML_(dinfo_zalloc)(cc, size);
 296    if (size > 0)
 297       ML_(cur_read_get)(dst, c, size);
 298    return dst;
 299 }
 300
 301 static inline UChar ML_(cur_read_UChar) ( DiCursor c ) {
 302    UChar r = ML_(img_get_UChar)( c.img, c.ioff );
 303    return r;
 304 }
 305 static inline UChar ML_(cur_step_UChar)( DiCursor* c ) {
 306    UChar r = ML_(img_get_UChar)( c->img, c->ioff );
 307    c->ioff += sizeof(UChar);
 308    return r;
 309 }
 310
 311 static inline UShort ML_(cur_read_UShort) ( DiCursor c ) {
 312    UShort r = ML_(img_get_UShort)( c.img, c.ioff );
 313    return r;
 314 }
 315 static inline UShort ML_(cur_step_UShort) ( DiCursor* c ) {
 316    UShort r = ML_(img_get_UShort)( c->img, c->ioff );
 317    c->ioff += sizeof(UShort);
 318    return r;
 319 }
 320 static inline Short ML_(cur_step_Short) ( DiCursor* c ) {
 321    return (Short)ML_(cur_step_UShort)( c );
 322 }
 323
 324 static inline UInt ML_(cur_read_UInt) ( DiCursor c ) {
 325    UInt r = ML_(img_get_UInt)( c.img, c.ioff );
 326    return r;
 327 }
 328 static inline UInt ML_(cur_step_UInt) ( DiCursor* c ) {
 329    UInt r = ML_(img_get_UInt)( c->img, c->ioff );
 330    c->ioff += sizeof(UInt);
 331    return r;
 332 }
 333 static inline Int ML_(cur_step_Int) ( DiCursor* c ) {
 334    return (Int)ML_(cur_step_UInt)( c );
 335 }
 336
 337 static inline ULong ML_(cur_read_ULong) ( DiCursor c ) {
 338    ULong r = ML_(img_get_ULong)( c.img, c.ioff );
 339    return r;
 340 }
 341 static inline ULong ML_(cur_step_ULong) ( DiCursor* c ) {
 342    ULong r = ML_(img_get_ULong)( c->img, c->ioff );
 343    c->ioff += sizeof(ULong);
 344    return r;
 345 }
 346 static inline Long ML_(cur_step_Long) ( DiCursor* c ) {
 347    return (Long)ML_(cur_step_ULong)( c );
 348 }
 349
 350 static inline Addr ML_(cur_step_Addr) ( DiCursor* c ) {
 351    if (sizeof(Addr) == sizeof(UInt)) {
 352       return ML_(cur_step_UInt)(c);
 353    } else if  (sizeof(Addr) == sizeof(ULong)) {
 354       return ML_(cur_step_ULong)(c);
 355    } else {
 356       vg_assert(0);
 357    }
 358 }
 359
 360 #endif /* ndef __PRIV_IMAGE_H */
 361
 362 /*--------------------------------------------------------------------*/
 363 /*--- end                                             priv_image.h ---*/
 364 /*--------------------------------------------------------------------*/