src/ld/debugline.h

   1 /*
   2  * Copyright (c) 2006 Apple, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23 #ifndef __DEBUG_LINE_H__
  24 #define __DEBUG_LINE_H__
  25
  26 #include <stdint.h>
  27 #include <stddef.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /* Information about a line.
  34    DIRECTORY is to be ignored if FILENAME is absolute.
  35    PC will be relative to the file the debug_line section is in.  */
  36 struct line_info
  37 {
  38   uint64_t file;
  39   int64_t line;
  40   uint64_t col;
  41   uint64_t pc;
  42   int end_of_sequence;
  43 };
  44
  45 /* Opaque status structure for the line readers.  */
  46 struct line_reader_data;
  47
  48 /* Create a line_reader_data, given address and size of the debug_line section.
  49    SIZE may be (size_t)-1 if unknown, although this suppresses checking
  50    for an incorrectly large size in the debug_line section.
  51    LITTLE_ENDIAN is set if the debug_line section is for a little-endian
  52    machine.
  53    Returns NULL on error.  */
  54 struct line_reader_data * line_open (const uint8_t * debug_line,
  55                                      size_t debug_line_size,
  56                                      int little_endian);
  57
  58 /* The STOP parameter to line_next is one of line_stop_{file,line,col},
  59    perhaps ORed with line_stop_pc; or line_stop_atend, or line_stop_always.  */
  60 enum line_stop_constants {
  61   line_stop_atend = 0, /* Stop only at the end of a sequence.  */
  62   line_stop_file = 1,  /* Stop if DIRECTORY or FILENAME change.  */
  63   line_stop_line = 2,  /* Stop if LINE, DIRECTORY, or FILENAME change.  */
  64   line_stop_col = 3,   /* Stop if COL, LINE, DIRECTORY, or FILENAME change.  */
  65   line_stop_pos_mask = 3,
  66   line_stop_pc = 4,    /* Stop if PC changes.  */
  67   line_stop_always = 8 /* Stop always.  */
  68 };
  69
  70 /* Either return FALSE on an error, in which case the line_reader_data
  71    may be invalid and should be passed immediately to line_free; or
  72    fill RESULT with the first 'interesting' line, as determined by STOP.
  73    The last line data in a sequence is always considered 'interesting'.  */
  74 int line_next (struct line_reader_data * lnd,
  75                 struct line_info * result,
  76                 enum line_stop_constants stop);
  77
  78 /* Find the region (START->pc through END->pc) in the debug_line
  79    information which contains PC.  This routine starts searching at
  80    the current position (which is returned as END), and will go all
  81    the way around the debug_line information.  It will return false if
  82    an error occurs or if there is no matching region; these may be
  83    distinguished by looking at START->end_of_sequence, which will be
  84    false on error and true if there was no matching region.
  85    You could write this routine using line_next, but this version
  86    will be slightly more efficient, and of course more convenient.  */
  87
  88 int line_find_addr (struct line_reader_data * lnd,
  89                      struct line_info * start,
  90                      struct line_info * end,
  91                      uint64_t pc);
  92
  93 /* Return TRUE if there is more line data to be fetched.
  94    If line_next has not been called or it has been called but did not
  95    set END_OF_SEQUENCE, you can assume there is more line data,
  96    but it's safe to call this routine anyway.  */
  97 int line_at_eof (struct line_reader_data * lnd);
  98
  99 /* Return the pathname of the file in S, or NULL on error.
 100    The result will have been allocated with malloc.  */
 101 char * line_file (struct line_reader_data *lnd, uint64_t file);
 102
 103 /* Reset the line_reader_data: go back to the beginning.  */
 104 void line_reset (struct line_reader_data * lnd);
 105
 106 /* Free a line_reader_data structure.  */
 107 void line_free (struct line_reader_data * lnd);
 108
 109 #ifdef __cplusplus
 110 }
 111 #endif
 112
 113 #endif // __DEBUG_LINE_H__
 114