ruby-elf 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -110,6 +110,11 @@ bss column, this counts in the size of sections that are allocated at runtime as
110
110
  section\&.
111
111
  .RE
112
112
  .PP
113
+ overhead
114
+ .RS 4
115
+ Total size of sections providing object\*(Aqs metadata for the link editor and dynamic loader\&. These include the symbol and string tables, the version tables and the hash table used during linking and execution\&. These values are usually tied to the amount of symbols exposed by an object, and can easily be reduced by hiding internal, non\-public symbols\&.
116
+ .RE
117
+ .PP
113
118
  total
114
119
  .RS 4
115
120
  Counts in the sum of all the previous sections\&.
@@ -0,0 +1,334 @@
1
+ <?xml version='1.0'?>
2
+ <!--
3
+ Copyright © 2008-2011, Diego "Flameeyes" Pettenò <flameeyes@gmail.com>
4
+
5
+ This program is free software; you can redistribute it and/or modify
6
+ it under the terms of the GNU General Public License as published by
7
+ the Free Software Foundation; either version 2 of the License, or
8
+ (at your option) any later version.
9
+
10
+ This program is distributed in the hope that it will be useful,
11
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
12
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13
+ GNU General Public License for more details.
14
+
15
+ You should have received a copy of the GNU General Public License
16
+ along with this generator; if not, write to the Free Software
17
+ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18
+ -->
19
+ <article xmlns="http://docbook.org/ns/docbook"
20
+ xmlns:xl="http://www.w3.org/1999/xlink"
21
+ xmlns:xi="http://www.w3.org/2001/XInclude"
22
+ version="5.0" xml:lang="en">
23
+ <info>
24
+ <title>rbelf-size</title>
25
+
26
+ <xi:include parse="xml" href="author.xmli" />
27
+ </info>
28
+
29
+ <section>
30
+ <title>Reference</title>
31
+
32
+ <refentry>
33
+ <info>
34
+ <date>October 2008</date>
35
+ <productname>ruby-elf</productname>
36
+ </info>
37
+ <refmeta>
38
+ <refentrytitle>rbelf-size</refentrytitle>
39
+ <manvolnum>1</manvolnum>
40
+ </refmeta>
41
+ <refnamediv>
42
+ <refname>rbelf-size</refname>
43
+ <refpurpose>List section sizes of ELF files</refpurpose>
44
+ </refnamediv>
45
+ <refsynopsisdiv>
46
+ <cmdsynopsis>
47
+ <command>rbelf-size</command>
48
+
49
+ <arg choice="opt">
50
+ <option>--relocation-stats</option>
51
+ <arg choice="opt"><option>--decibel</option></arg>
52
+ </arg>
53
+
54
+ <xi:include href="common.xmli" xpointer="xpointer(id('filelist.synopsis')/*)" />
55
+ </cmdsynopsis>
56
+ </refsynopsisdiv>
57
+
58
+ <refsect1>
59
+ <title>Description</title>
60
+ <para>
61
+ <command>rbelf-size</command> is a replacement for the standard
62
+ <citerefentry><refentrytitle>size</refentrytitle><manvolnum>1</manvolnum></citerefentry>
63
+ utility, as provided by GNU binutils and similar suites. Instead of showing the sum of all
64
+ the invariant, variant and unallocated sections as the size, it divides them depending on
65
+ how they are treated, differentiating between invariant data, invariant code, variant data
66
+ and relocated invariant data.
67
+ </para>
68
+ </refsect1>
69
+
70
+ <refsect1>
71
+ <title>Options</title>
72
+
73
+ <variablelist>
74
+ <varlistentry>
75
+ <term><option>-r</option></term>
76
+ <term><option>--relocation-stats</option></term>
77
+ <listitem>
78
+ <para>
79
+ Instead of reporting size data compatible with
80
+ <citerefentry><refentrytitle>size</refentrytitle><manvolnum>1</manvolnum></citerefentry>
81
+ report size for shared, private and relocated areas. This is helpful to assess the
82
+ validity of shared object approaches.
83
+ </para>
84
+ </listitem>
85
+ </varlistentry>
86
+
87
+ <varlistentry>
88
+ <term><option>-d</option></term>
89
+ <term><option>--decibel</option></term>
90
+ <listitem>
91
+ <para>
92
+ When using the <option>--relocation-stats</option> option, a ratio is displayed
93
+ between the size of relocated and shared code areas, to better assess the advantages
94
+ and disadvantages for shared object approaches.
95
+ </para>
96
+
97
+ <para>
98
+ Since that ratio can easily skyrocket into thousands if there is very little
99
+ relocated data, and a lot of shared data, it might be easier to appreciate the
100
+ results by using a logaritmic scale.
101
+ </para>
102
+ </listitem>
103
+ </varlistentry>
104
+
105
+ <xi:include href="common.xmli" xpointer="xpointer(id('filelist.option')/*)" />
106
+ </variablelist>
107
+ </refsect1>
108
+
109
+ <refsect1>
110
+ <title>Compatible Output</title>
111
+
112
+ <para>
113
+ The output of <command>rbelf-size</command> differs from that of <command>size</command>
114
+ for the number and type of columns it outputs. While the original BSD command outputs the
115
+ size of the "text", "data" and "bss" sections, this tool splits them further.
116
+ </para>
117
+
118
+ <variablelist>
119
+ <varlistentry>
120
+ <term>exec</term>
121
+ <listitem>
122
+ <para>
123
+ Counts in all the sections containing executable code, this includes the
124
+ <varname>.text</varname> section, and others.
125
+ </para>
126
+ </listitem>
127
+ </varlistentry>
128
+
129
+ <varlistentry>
130
+ <term>data</term>
131
+ <listitem>
132
+ <para>
133
+ Counts in all the sections containing variable data, this excludes read-only data
134
+ sections, but includes relocated data and other kind of allocated and writeable data
135
+ sections. If the compiler is GCC or outputs GCC-compatible section names this won't
136
+ count in relocated constants.
137
+ </para>
138
+ </listitem>
139
+ </varlistentry>
140
+
141
+ <varlistentry>
142
+ <term>relro</term>
143
+ <listitem>
144
+ <para>
145
+ Counts in the relocated constants (read-only relocated data). This column will be
146
+ non-null only for binaries compiled by GCC or by compilers emitting GCC-compatible
147
+ section names. The sections counted in this entry will are relocated at runtime, but
148
+ are never otherwise modified. The reason why this is separated is that this section
149
+ may be touched by
150
+ <citerefentry><refentrytitle>prelink</refentrytitle><manvolnum>8</manvolnum></citerefentry>
151
+ so that the runtime relocation is not needed, and thus would count just as common
152
+ constant data.
153
+ </para>
154
+ </listitem>
155
+ </varlistentry>
156
+
157
+ <varlistentry>
158
+ <term>bss</term>
159
+ <listitem>
160
+ <para>
161
+ Just like <command>size</command> bss column, this counts in the size of sections
162
+ that are allocated at runtime as mapped to the zero page. It supports TLS
163
+ <varname>.tbss</varname> section.
164
+ </para>
165
+ </listitem>
166
+ </varlistentry>
167
+
168
+ <varlistentry>
169
+ <term>overhead</term>
170
+ <listitem>
171
+ <para>
172
+ Total size of sections providing object's metadata for the link editor and dynamic
173
+ loader. These include the symbol and string tables, the version tables and the hash
174
+ table used during linking and execution. These values are usually tied to the amount
175
+ of symbols exposed by an object, and can easily be reduced by hiding internal,
176
+ non-public symbols.
177
+ </para>
178
+ </listitem>
179
+ </varlistentry>
180
+
181
+ <varlistentry>
182
+ <term>total</term>
183
+ <listitem>
184
+ <para>
185
+ Counts in the sum of all the previous sections.
186
+ </para>
187
+ </listitem>
188
+ </varlistentry>
189
+ </variablelist>
190
+ </refsect1>
191
+
192
+ <refsect1>
193
+ <title>Relocation Statistics</title>
194
+
195
+ <para>
196
+ When using shared objects rather than static linking, there are many trade-offs to be
197
+ made. One of these relates to the amount of code that will get relocated (and thus becomes
198
+ private, per-process resident memory).
199
+ </para>
200
+
201
+ <para>
202
+ The <option>--relocation-stats</option> option was devised as a mean to assess the
203
+ cost/benefit of using shared objects, rather than using static link (e.g. with multicall
204
+ binaries).
205
+ </para>
206
+
207
+ <variablelist>
208
+ <varlistentry>
209
+ <term>shared</term>
210
+ <listitem>
211
+ <para>
212
+ Areas of memory that are always shared among processes; these include executable
213
+ areas with Position Indipendent Code, and read-only data areas.
214
+ </para>
215
+
216
+ <para>
217
+ Generally, this is what we would want to have as big as possible, compared to the
218
+ rest.
219
+ </para>
220
+ </listitem>
221
+ </varlistentry>
222
+
223
+ <varlistentry>
224
+ <term>private</term>
225
+ <listitem>
226
+ <para>
227
+ Areas of memory that will always be private to the process; these includes writeable
228
+ data areas and areas remapped to the zero page (what above is called bss).
229
+ </para>
230
+
231
+ <para>
232
+ This is a worst-case value, as even though the writeable sections _may_ become
233
+ private, if they are left untouched they will be shared among multiple (if not all)
234
+ processes. It is, though, useful to consider the worst-case scenario for assesment.
235
+ </para>
236
+ </listitem>
237
+ </varlistentry>
238
+
239
+ <varlistentry>
240
+ <term>relocated</term>
241
+ <listitem>
242
+ <para>
243
+ This value sums up the size of the memory areas that will be relocated when using
244
+ shared objects (or Position Indipendent Executables). Relocated areas include
245
+ .data.rel.ro sections, which contain data read-only for the code, but written to by
246
+ the dynamic linker.
247
+ </para>
248
+
249
+ <para>
250
+ Again this value is an approximation nearing the worst-case scenario.
251
+ </para>
252
+ </listitem>
253
+ </varlistentry>
254
+
255
+ <varlistentry>
256
+ <term>ratio</term>
257
+ <listitem>
258
+ <para>
259
+ The ratio between shared and relocated code in the current executable or shared
260
+ object. Using this value you can have a quick idea of the cost/benefit of using
261
+ shared objects for a particular task.
262
+ </para>
263
+
264
+ <para>
265
+ When using <option>--decibel</option> the value will be represented in deciBels,
266
+ which should make it even easier to understand: a negative value shows a overly high
267
+ cost, while a value between 1 and 10 will indicate some work might be needed to
268
+ improve the benefits.
269
+ </para>
270
+ </listitem>
271
+ </varlistentry>
272
+ </variablelist>
273
+ </refsect1>
274
+
275
+ <refsect1>
276
+ <title>Bugs and Missing Features</title>
277
+
278
+ <para>
279
+ The name <varname>total</varname> for the sum of the colums is misleading since it's
280
+ actually not the total size of the file, nor the total size of the allocated entries.
281
+ </para>
282
+
283
+ <para>
284
+ Right now, all the sections are counted in if their flags match, it might be better to
285
+ limit to allocated sections all over the place.
286
+ </para>
287
+
288
+ <para>
289
+ The size of the columns is fixed to 8 digits, it might not be enough to fill in enough
290
+ space for some big ELF files.
291
+ </para>
292
+
293
+ <xi:include href="common.xmli" xpointer="xpointer(id('filelist.bugpara')/*)" />
294
+ </refsect1>
295
+
296
+ <refsect1>
297
+ <title>See Also</title>
298
+ <para>
299
+ <citation xl:href="http://blog.flameeyes.eu/">Flameeyes's Weblog</citation>
300
+ http://blog.flameeyes.eu/
301
+ </para>
302
+
303
+ <para>
304
+ Related tools:
305
+
306
+ <citerefentry>
307
+ <refentrytitle>cowstats</refentrytitle>
308
+ <manvolnum>1</manvolnum>
309
+ </citerefentry>,
310
+
311
+ <citerefentry>
312
+ <refentrytitle>size</refentrytitle>
313
+ <manvolnum>1</manvolnum>
314
+ </citerefentry>,
315
+
316
+ <citerefentry>
317
+ <refentrytitle>prelink</refentrytitle>
318
+ <manvolnum>8</manvolnum>
319
+ </citerefentry>.
320
+ </para>
321
+ </refsect1>
322
+ </refentry>
323
+ </section>
324
+ </article>
325
+ <!--
326
+ Local Variables:
327
+ mode: nxml
328
+ mode: auto-fill
329
+ mode: flyspell
330
+ ispell-local-dictionary: "english"
331
+ fill-column: 100
332
+ indent-tabs-mode: nil
333
+ End:
334
+ -->
@@ -0,0 +1,136 @@
1
+ <?xml version='1.0'?>
2
+ <!--
3
+ Copyright © 2010-2011, Diego "Flameeyes" Pettenò <flameeyes@gmail.com>
4
+
5
+ This program is free software; you can redistribute it and/or modify
6
+ it under the terms of the GNU General Public License as published by
7
+ the Free Software Foundation; either version 2 of the License, or
8
+ (at your option) any later version.
9
+
10
+ This program is distributed in the hope that it will be useful,
11
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
12
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13
+ GNU General Public License for more details.
14
+
15
+ You should have received a copy of the GNU General Public License
16
+ along with this generator; if not, write to the Free Software
17
+ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18
+ -->
19
+ <article xmlns="http://docbook.org/ns/docbook"
20
+ xmlns:xl="http://www.w3.org/1999/xlink"
21
+ xmlns:xi="http://www.w3.org/2001/XInclude"
22
+ version="5.0" xml:lang="en">
23
+ <info>
24
+ <title>verify-lfs</title>
25
+
26
+ <xi:include parse="xml" href="author.xmli" />
27
+ </info>
28
+
29
+ <section>
30
+ <title>Reference</title>
31
+
32
+ <refentry>
33
+ <info>
34
+ <date>December 2010</date>
35
+ <productname>ruby-elf</productname>
36
+ </info>
37
+ <refmeta>
38
+ <refentrytitle>verify-lfs</refentrytitle>
39
+ <manvolnum>1</manvolnum>
40
+ </refmeta>
41
+ <refnamediv>
42
+ <refname>verify-lfs</refname>
43
+ <refpurpose>ELF analyzer to identify software not using solely LFS interfaces</refpurpose>
44
+ </refnamediv>
45
+ <refsynopsisdiv>
46
+ <cmdsynopsis>
47
+ <command>verify-lfs</command>
48
+
49
+ <arg choice="opt">
50
+ <option>--objects</option>
51
+ </arg>
52
+
53
+ <xi:include href="common.xmli" xpointer="xpointer(id('filelist.synopsis')/*)" />
54
+ </cmdsynopsis>
55
+ </refsynopsisdiv>
56
+
57
+ <refsect1>
58
+ <title>Description</title>
59
+ <para>
60
+ <command>verify-lfs</command> is a script that analyses the symbols required by ELF
61
+ executables and libraries, listing the objects that rely entirely or partially on the
62
+ pre-largefile interface functions of glibc.
63
+ </para>
64
+ </refsect1>
65
+
66
+ <refsect1>
67
+ <title>Options</title>
68
+
69
+ <variablelist>
70
+ <varlistentry>
71
+ <term><option>-o</option></term>
72
+ <term><option>--objects</option></term>
73
+
74
+ <listitem>
75
+ <para>
76
+ Scan for relocatable object files (ET_REL) rather than executables or dynamic
77
+ libraries. This mode is designed to help identify which object might be miscompiled
78
+ to not use LFS functions as it was instead intended.
79
+ </para>
80
+ </listitem>
81
+ </varlistentry>
82
+
83
+ <xi:include href="common.xmli" xpointer="xpointer(id('filelist.option')/*)" />
84
+ </variablelist>
85
+ </refsect1>
86
+
87
+ <refsect1>
88
+ <title>Bugs and Missing Features</title>
89
+ <para>
90
+ <command>verify-lfs</command> uses a manually-tweaked regular expression to identify which
91
+ interface is being used; this expressions might be incomplete or lead to false positive,
92
+ please double-check the results, and report back if you have hit false positives, or false
93
+ negatives.
94
+ </para>
95
+
96
+ <xi:include href="common.xmli" xpointer="xpointer(id('filelist.bugpara')/*)" />
97
+ </refsect1>
98
+
99
+ <refsect1>
100
+ <title>Credits</title>
101
+
102
+ <para>
103
+ The original idea for this script comes from the <filename>summarise-stat64</filename>
104
+ Perl script written by Greg Banks of SGI. A huge thanks to Greg for the idea and the
105
+ script.
106
+ </para>
107
+ </refsect1>
108
+
109
+ <refsect1>
110
+ <title>See Also</title>
111
+ <para>
112
+ <citation xl:href="http://blog.flameeyes.eu/">Flameeyes's Weblog</citation>
113
+ http://blog.flameeyes.eu/
114
+ </para>
115
+
116
+ <para>
117
+ Related tools:
118
+ <citerefentry>
119
+ <refentrytitle>nm</refentrytitle>
120
+ <manvolnum>1</manvolnum>
121
+ </citerefentry>.
122
+ </para>
123
+ </refsect1>
124
+ </refentry>
125
+ </section>
126
+ </article>
127
+ <!--
128
+ Local Variables:
129
+ mode: nxml
130
+ mode: auto-fill
131
+ mode: flyspell
132
+ ispell-local-dictionary: "english"
133
+ fill-column: 100
134
+ indent-tabs-mode: nil
135
+ End:
136
+ -->