src/ld/debugline.h

/*
 * Copyright (c) 2006 Apple, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 */
#ifndef __DEBUG_LINE_H__
#define __DEBUG_LINE_H__

#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Information about a line.
   DIRECTORY is to be ignored if FILENAME is absolute.
   PC will be relative to the file the debug_line section is in.  */
struct line_info
{
  uint64_t file;
  int64_t line;
  uint64_t col;
  uint64_t pc;
  int end_of_sequence;
};

/* Opaque status structure for the line readers.  */
struct line_reader_data;

/* Create a line_reader_data, given address and size of the debug_line section.
   SIZE may be (size_t)-1 if unknown, although this suppresses checking
   for an incorrectly large size in the debug_line section.
   LITTLE_ENDIAN is set if the debug_line section is for a little-endian
   machine.
   Returns NULL on error.  */
struct line_reader_data * line_open (const uint8_t * debug_line,
				     size_t debug_line_size,
				     int little_endian);

/* The STOP parameter to line_next is one of line_stop_{file,line,col},
   perhaps ORed with line_stop_pc; or line_stop_atend, or line_stop_always.  */
enum line_stop_constants {
  line_stop_atend = 0, /* Stop only at the end of a sequence.  */
  line_stop_file = 1,  /* Stop if DIRECTORY or FILENAME change.  */
  line_stop_line = 2,  /* Stop if LINE, DIRECTORY, or FILENAME change.  */
  line_stop_col = 3,   /* Stop if COL, LINE, DIRECTORY, or FILENAME change.  */
  line_stop_pos_mask = 3,
  line_stop_pc = 4,    /* Stop if PC changes.  */
  line_stop_always = 8 /* Stop always.  */
};

/* Either return FALSE on an error, in which case the line_reader_data
   may be invalid and should be passed immediately to line_free; or
   fill RESULT with the first 'interesting' line, as determined by STOP.
   The last line data in a sequence is always considered 'interesting'.  */
int line_next (struct line_reader_data * lnd,
		struct line_info * result,
		enum line_stop_constants stop);

/* Find the region (START->pc through END->pc) in the debug_line
   information which contains PC.  This routine starts searching at
   the current position (which is returned as END), and will go all
   the way around the debug_line information.  It will return false if
   an error occurs or if there is no matching region; these may be
   distinguished by looking at START->end_of_sequence, which will be
   false on error and true if there was no matching region.
   You could write this routine using line_next, but this version
   will be slightly more efficient, and of course more convenient.  */

int line_find_addr (struct line_reader_data * lnd,
		     struct line_info * start,
		     struct line_info * end,
		     uint64_t pc);

/* Return TRUE if there is more line data to be fetched.
   If line_next has not been called or it has been called but did not
   set END_OF_SEQUENCE, you can assume there is more line data,
   but it's safe to call this routine anyway.  */
int line_at_eof (struct line_reader_data * lnd);

/* Return the pathname of the file in S, or NULL on error.
   The result will have been allocated with malloc.  */
char * line_file (struct line_reader_data *lnd, uint64_t file);

/* Reset the line_reader_data: go back to the beginning.  */
void line_reset (struct line_reader_data * lnd);

/* Free a line_reader_data structure.  */
void line_free (struct line_reader_data * lnd);

#ifdef __cplusplus
}
#endif

#endif // __DEBUG_LINE_H__
Commit	Line	Data
	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