From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 23756 invoked by alias); 24 Jan 2005 22:47:24 -0000 Mailing-List: contact binutils-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: binutils-owner@sources.redhat.com Received: (qmail 23543 invoked from network); 24 Jan 2005 22:46:56 -0000 Received: from unknown (HELO sam.opera.com) (193.69.113.81) by sourceware.org with SMTP; 24 Jan 2005 22:46:56 -0000 Received: from whorl.oslo.opera.com (pc123.lan019.oslo.opera.com [10.20.19.123] (may be forged)) by sam.opera.com (8.12.3/8.12.3/Debian-6.6) with ESMTP id j0OMkblB007054; Mon, 24 Jan 2005 22:46:37 GMT Received: from eddy by whorl.oslo.opera.com with local (Exim 3.36 #1 (Debian)) id 1CtCyj-0000TM-00; Mon, 24 Jan 2005 23:46:37 +0100 To: ian@airs.com CC: amodra@bigpond.net.au, bug-binutils@gnu.org, binutils@sources.redhat.com In-reply-to: (message from Ian Lance Taylor on 24 Jan 2005 14:02:36 -0500) Subject: Re: binutils-doc 2.15-5: glitches in ld.info Reply-to: eddy@opera.com References: <20050123074306.GB18895@bubble.modra.org> User-Agent: SEMI/1.14.6 (Maruoka) FLIM/1.14.6 (Marutamachi) APEL/10.6 Emacs/21.3 (i386-pc-linux-gnu) MULE/5.0 (SAKAKI) MIME-Version: 1.0 (generated by SEMI 1.14.6 - "Maruoka") Content-Type: text/plain; charset=US-ASCII Message-Id: From: Edward Welbourne Date: Mon, 24 Jan 2005 22:47:00 -0000 X-SW-Source: 2005-01/txt/msg00394.txt.bz2 > 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 You may assign a value to a symbol in a linker script. This will define the symbol as a global symbol. 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