1.\"	$NetBSD: dwarf_add_frame_fde.3,v 1.2 2014/03/09 16:58:03 christos Exp $
2.\"
3.\" Copyright (c) 2011 Kai Wang
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.\" Id: dwarf_add_frame_fde.3 2072 2011-10-27 03:26:49Z jkoshy
28.\"
29.Dd September 26, 2011
30.Os
31.Dt DWARF_ADD_FRAME_FDE 3
32.Sh NAME
33.Nm dwarf_add_frame_fde
34.Nd add a call frame descriptor to a DWARF producer instance
35.Sh LIBRARY
36.Lb libdwarf
37.Sh SYNOPSIS
38.In libdwarf.h
39.Ft "Dwarf_Unsigned"
40.Fo dwarf_add_frame_fde
41.Fa "Dwarf_P_Debug dbg"
42.Fa "Dwarf_P_Fde fde"
43.Fa "Dwarf_P_Die die"
44.Fa "Dwarf_Unsigned cie"
45.Fa "Dwarf_Addr virt_addr"
46.Fa "Dwarf_Unsigned code_len"
47.Fa "Dwarf_Unsigned symbol_index"
48.Fa "Dwarf_Error *err"
49.Fc
50.Ft "Dwarf_Unsigned"
51.Fo dwarf_add_frame_fde_b
52.Fa "Dwarf_P_Debug dbg"
53.Fa "Dwarf_P_Fde fde"
54.Fa "Dwarf_P_Die die"
55.Fa "Dwarf_Unsigned cie"
56.Fa "Dwarf_Addr virt_addr"
57.Fa "Dwarf_Unsigned code_len"
58.Fa "Dwarf_Unsigned symbol_index"
59.Fa "Dwarf_Unsigned end_symbol_index"
60.Fa "Dwarf_Addr offset_from_end_sym"
61.Fa "Dwarf_Error *err"
62.Fc
63.Sh DESCRIPTION
64Function
65.Fn dwarf_add_frame_fde_b
66adds the call frame descriptor referenced by argument
67.Ar fde
68to a producer instance.
69.Pp
70Argument
71.Ar dbg
72should reference a DWARF producer instance allocated using
73.Xr dwarf_producer_init 3
74or
75.Xr dwarf_producer_init_b 3 .
76.Pp
77Argument
78.Ar fde
79should reference a frame descriptor allocated using
80.Xr dwarf_new_fde 3 .
81.Pp
82Argument
83.Ar die
84is ignored by this implementation of the
85.Lb libdwarf .
86.Pp
87Argument
88.Ar cie
89specifies the index of call frame common information entry for
90the frame descriptor.
91Valid indices are those returned by the function
92.Xr dwarf_add_frame_cie 3 .
93.Pp
94Argument
95.Ar symbol_index
96specifies the ELF symbol index of the first symbol to be used for
97relocation.
98.Pp
99The meaning of the arguments
100.Ar virt_addr ,
101.Ar code_len
102and
103.Ar offset_from_end_sym
104depend on the value of argument
105.Ar end_symbol_index :
106.Bl -bullet
107.It
108If the argument
109.Ar end_symbol_index
110is zero, the argument
111.Ar virt_addr
112specifies the relocatable address of the start of the function
113associated with the frame descriptor, the argument
114.Ar code_len
115specifies the size in bytes of the machine instructions for this
116function, the argument
117.Ar symbol_index
118specifies the ELF symbol to be used for relocating the address in
119argument
120.Ar virt_addr ,
121and the argument
122.Ar offset_from_end_symbol
123is ignored.
124.It
125If the argument
126.Ar end_symbol_index
127is non-zero, it specifies the ELF symbol index of the second symbol to
128be used for relocation.
129In this case, the argument
130.Ar virt_addr
131specifies an offset from the relocatable symbol specified by argument
132.Ar symbol_index ,
133the argument
134.Ar offset_from_end_symbol
135should specify an offset from the symbol named by the argument
136.Ar end_symbol_index ,
137and the argument
138.Ar code_len
139will be ignored.
140The
141.Dv DW_DLC_SYMBOLIC_RELOCATIONS
142flag should also have been set on the DWARF producer instance.
143.Pp
144Application code can retrieve the relocation entries for the symbol
145pair by calling function
146.Xr dwarf_get_relocation_info 3 .
147The relocation entry for the first symbol will have type
148.Dv dwarf_drt_first_of_length_pair
149and the relocation entry for the second symbol will have type
150.Dv dwarf_drt_second_of_length_pair .
151.El
152.Pp
153If argument
154.Ar err
155is not NULL, it will be used to store error information in case
156of an error.
157.Pp
158Function
159.Fn dwarf_add_frame_fde
160is similar to function
161.Fn dwarf_add_frame_fde_b
162except that it supports only one relocation symbol.
163.Sh RETURN VALUES
164On success, these functions return the index value for
165the added frame descriptor.
166In case of an error, these functions return
167.Dv DW_DLV_NOCOUNT
168and set the argument
169.Ar err .
170.Sh ERRORS
171These functions can fail with:
172.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
173.It Bq Er DW_DLE_ARGUMENT
174One of the arguments
175.Ar dbg
176or
177.Ar fde
178was NULL.
179.It Bq Er DW_DLE_ARGUMENT
180The frame descriptor referenced by argument
181.Ar fde
182did not belong to the producer instance referenced by argument
183.Ar dbg .
184.It Bq Er DW_DLE_ARGUMENT
185The common information entry index specified by argument
186.Ar cie
187was invalid.
188.It Bq Er DW_DLE_ARGUMENT
189Argument
190.Ar end_symbol_index
191was non-zero, but the flag
192.Dv DW_DLC_SYMBOLIC_RELOCATIONS
193was not set on the producer instance.
194.El
195.Sh SEE ALSO
196.Xr dwarf 3 ,
197.Xr dwarf_add_fde_inst 3 ,
198.Xr dwarf_add_frame_cie 3 ,
199.Xr dwarf_fde_cfa_offset 3 ,
200.Xr dwarf_get_relocation_info 3 ,
201.Xr dwarf_new_fde 3 ,
202.Xr dwarf_producer_init 3 ,
203.Xr dwarf_producer_init_b 3
204