[Bug ld/10774] Bogus documentation

[nickc at redhat dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=10774

Nick Clifton <nickc at redhat dot com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |ASSIGNED
                 CC|                            |nickc at redhat dot com

--- Comment #1 from Nick Clifton <nickc at redhat dot com> ---
Hi Konrad,

  Sorry for letting this PR languish for so long.

  I agree that the wording of the Source Code Reference section is wrong, but I
think that your proposed replacement is a little bit too terse.  I particularly
want to include the memcpy examples as it was precisely this piece of code that
tripped up a customer and caused them to file a bogus bug report.  Thus please
could you tell me if you are happy with the following replacement version
instead:

Cheers
  Nick

3.5.5 Source Code Reference
---------------------------

The value of a symbol is its address.  Thus to access a symbol's value
from a high level language it should be declared as an external variable
and its address used.

   Note that in most cases, symbols defined by linker scripts do _not_
have any associated storage assigned to them, so it is typically an
error to read from or write to such an external variable.  For example,
suppose that a linker script defines some symbols like this:

       start_of_ROM   = .ROM;
       end_of_ROM     = .ROM + sizeof (.ROM);
       start_of_FLASH = .FLASH;

   The the following code to copy data from ROM to FLASH will fail:

       extern char start_of_ROM, end_of_ROM, start_of_FLASH;
       memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM); /*
FAIL */

   This is because it is reading from the symbols.  Instead the copy
should be written as:

       extern char start_of_ROM, end_of_ROM, start_of_FLASH;
       memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - &
start_of_ROM);

   Note the use of the '&' operators - these are correct.  Or the copy
could be written as:

       extern char start_of_ROM[], end_of_ROM[], start_of_FLASH[];
       memcpy (start_of_FLASH, start_of_ROM, end_of_ROM - start_of_ROM);

   Which is easier to read and enables the C compiler to diagnose
writes, reads (without array dereference) and use of the sizeof operator
as errors.

   Type checking is not performed on linker symbols, so any type can be
used to reference them.  Note however that using the wrong type could
lead to runtime problems.  For example:

       extern int start_of_FLASH[];
       * start_of_FLASH = 1;

   This could result in a runtime failure if the start_of_FLASH symbol
is not assigned to an address that meets the alignment requirements of
the int data type.

   Finally, note that some systems perform a transformation between
variable names as used in a high-level language and symbol names as seen
by the linker.  The transformation can be an artefact of the high level
language - for example name mangling in C++, or it can be part of the
architecture's ABI - for example prepending an underscore to variable
names.  If a linker script symbol is to be accessed from a high level
language then this transformation must be taken into account.  For
example in C a linker script symbol might be referred to as:

       extern int foo[];

   But in the linker script it might need to be defined as:

       _foo = 1000;

-- 
You are receiving this mail because:
You are on the CC list for the bug.