This is the mail archive of the binutils@sources.redhat.com mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: binutils-doc 2.15-5: glitches in ld.info


> Documentation updates are always welcome.

OK.  (ld) Assigning Values to Symbols
===========================
seems like the place where I believe something is worth saying about
this.  I am poorly qualified to write it, since the foregoing
discussion is all I know about it.  None the less ...

The section presently comprises a short paragraph <quote>

You may assign a value to a symbol in a linker script.  This will define
the symbol as a global symbol.

</quote> followed by a menu of two sub-topics.  I suggest adding to
that paragraph, so as to set context, and adding a third sub-section,
given below as after the existing two.  I am sure it can be greatly
improved, if only because I'm not much good at terseness.  A patch
follows, but I do not know enough about .info files to know what to do
about its Tag Table.  Hmm ... .info files are generated, but I don't
have the source file for it.  If the simple text of the modified
section would be more useful, please let me know; or point me to a
copy of the source form and I'll send a patch for it.

	Eddy.
-- 
diff -bu ld.info.orig ld.info
--- ld.info.orig	2004-11-25 01:24:28.000000000 +0100
+++ ld.info		2005-01-24 23:18:39.000000000 +0100
@@ -2063,12 +2063,14 @@
 ===========================
 
 You may assign a value to a symbol in a linker script.  This will define
-the symbol as a global symbol.
+the symbol as a global symbol: it creates an entry in the symbol table,
+which the linker uses to resolve references to the symbol.
 
 * Menu:
 
 * Simple Assignments::		Simple Assignments
 * PROVIDE::			PROVIDE
+* Source Code Reference::	How the symbol appears to the program.
 
 
 File: ld.info,  Node: Simple Assignments,  Next: PROVIDE,  Up: Assignments
@@ -2128,7 +2130,7 @@
 boundary.
 
 
-File: ld.info,  Node: PROVIDE,  Prev: Simple Assignments,  Up: Assignments
+File: ld.info, Node: PROVIDE, Next: Source Code Reference, Prev: Simple Assignments, Up: Assignments
 
 PROVIDE
 -------
@@ -2160,6 +2162,80 @@
 will use the definition in the linker script.
 
 
+File: ld.info,  Node: Source Code Reference, Prev: PROVIDE, Up: Assignments
+
+Source Code Reference
+---------------------
+
+When it is necessary for a program to reference symbols assigned by
+its linker script, it is important to understand the relationship
+between entries in the symbol table and the semantics of variables in
+your program's source code.  The short story is that the linker's
+symbol table records the addresses of objects with external linkage: a
+linker script assignment says where an object is in memory.
+
+Before going further, we must note that the compiler for your
+programming language may transform the names in your source code, so
+that their names in the resulting symbol tables will not match the
+names you use in your source code; for example, Fortran compilers
+commonly prepend or append an underscore, and C++ performs extensive
+"name mangling".  You should consult your compiler's manual for
+details; you shall need to use the correctly transformed name in your
+linker script, to match the name you use in your source code.
+
+However, it is usual for C compilers to use source names verbatim in
+the symbol table, so we shall use C in what follows.  In C++, it is
+possible to have a name treated "as if" in C (i.e. without
+name-mangling) by declaring it in the extern "C" namespace.
+
+Only symbols your program declares with "external linkage" will appear
+in (or be resolved via) the symbol table: objects with "local linkage"
+(those declared static in file scope, in C) are not visible to the
+linker.  Objects your program defines (i.e. functions for which it
+provides bodies, and variables it declares at file scope, but does not
+declare "static") provide entries to the symbol table; your linker
+script cannot assign to their names - doing so would produce a
+duplicate symbol warning.  However, if your program declares a symbol
+with external linkage, but does not define it, then the linker will
+have to provide that symbol with a value.  Normally, this happens by
+some other object file providing a definition for the symbol, which
+the linker makes your use of the symbol refer to.
+
+However, the linker can also resolve your use of a symbol using a
+linker script assignment.  If your C program declares
+
+     extern int VAR;
+
+then the symbol table needs to say where VAR is to be stored in
+memory, so that your program's uses of VAR can be turned into read and
+write operations accessing that memory.  The symbol table records the
+start address of the piece of memory to be accessed: it knows nothing
+about its size (let alone its type), though the compiler will have
+caused your uses of VAR to access the right number of bytes following
+the start address.  If your linker script says
+
+     VAR = EXPRESSION
+
+then the value it computes for EXPRESSION will be used as the address
+at which VAR is stored: this is what your C program would see as &VAR.
+For an example of a C program refering to symbols set by a link
+script, see *Note Overlay Description.
+
+If the EXPRESSION evaluates to some address which your program is
+using in some other way, its references to VAR may well conflict with
+that use: the linker assumes you mean what you say, so it is up to you
+to ensure your link script provides a sensible EXPRESSION.
+
+Due to some quirks of C's type system (treating functions and arrays
+as synonyms for their addresses, in some respects - but not all) it is
+possible to declare an extern variable and have its value as seen by
+your C code coincide with the value assigned to it by your linker
+script.  However, thanks to related complications of C's type system,
+use of such quirks should be approached with caution.  It is safer to
+specify an ordinary type and have the fact that you are taking the
+variable's address be evident to anyone reading your program.
+
+
 File: ld.info,  Node: SECTIONS,  Next: MEMORY,  Prev: Assignments,  Up: Scripts
 
 SECTIONS Command

Diff finished at Mon Jan 24 23:19:03


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]