Help text for ld magic number options

Help text for ld magic number options

[Stephen Casner]

Thanks, Alan, for addressing bug 25569 more thoroughly than I would be
able to do.

To all, next I have three proposed changes related to the magic number
options for ld on which I solicit your feedback.  First a simple one.

The output of ld --help includes the following:

  -n, --nmagic     Do not page align data
  -N, --omagic     Do not page align data, do not make text readonly
  --no-omagic      Page align data, make text readonly

The help text for --nmagic is not accurate for the pdp11-aout target
and I believe not for others as well.  That option results in setting
config.text_read_only = TRUE, and in order to make the text read-only
the data must be aligned to a separate page on the PDP11 and I presume
for most if not all other computers as well.

The references to page alignment really correspond to the setting of
config.magic_demand_paged which, when TRUE, selects the ZMAGIC (0413)
format in aoutx.h.  That format does require the data to be page
aligned, but more significantly it indicates to the runtime system to
do demand paging.  The pdp11-aout code in bfd/pdp11.c does not
implement the ZMAGIC format (even though there is some stub code for
it included when copying from aoutx.h) since demand paging isn't
practical on the PDP11 and wasn't implemented for it over the full
timespan from Unix v6 through 2.11 BSD.  Thus, for pdp11-aout the
options --no-omagic and --nmagic produce the same result.

I propose that the help text be changed as follows:

  -n, --nmagic     Make text readonly, page align data, no demand paging
  -N, --omagic     Do not make text readonly, do not page align data
  --no-omagic      Make text readonly, page align data, do demand paging

Is that acceptable?  This would have implications for the ld
documentation as well.

                                                        -- Steve

Re: Help text for ld magic number options

[Fangrui Song]

On 2020-02-22, Stephen Casner wrote:
>Thanks, Alan, for addressing bug 25569 more thoroughly than I would be
>able to do.
>
>To all, next I have three proposed changes related to the magic number
>options for ld on which I solicit your feedback.  First a simple one.
>
>The output of ld --help includes the following:
>
>  -n, --nmagic     Do not page align data
>  -N, --omagic     Do not page align data, do not make text readonly
>  --no-omagic      Page align data, make text readonly
>
>The help text for --nmagic is not accurate for the pdp11-aout target
>and I believe not for others as well.  That option results in setting
>config.text_read_only = TRUE, and in order to make the text read-only
>the data must be aligned to a separate page on the PDP11 and I presume
>for most if not all other computers as well.
>
>The references to page alignment really correspond to the setting of
>config.magic_demand_paged which, when TRUE, selects the ZMAGIC (0413)
>format in aoutx.h.  That format does require the data to be page
>aligned, but more significantly it indicates to the runtime system to
>do demand paging.  The pdp11-aout code in bfd/pdp11.c does not
>implement the ZMAGIC format (even though there is some stub code for
>it included when copying from aoutx.h) since demand paging isn't
>practical on the PDP11 and wasn't implemented for it over the full
>timespan from Unix v6 through 2.11 BSD.  Thus, for pdp11-aout the
>options --no-omagic and --nmagic produce the same result.
>
>I propose that the help text be changed as follows:
>
>  -n, --nmagic     Make text readonly, page align data, no demand paging
>  -N, --omagic     Do not make text readonly, do not page align data
>  --no-omagic      Make text readonly, page align data, do demand paging
>
>Is that acceptable?  This would have implications for the ld
>documentation as well.
>

http://man.cat-v.org/unix_10th/5/a.out

           #define  OMAGIC    0407       /* old impure format */
           #define  NMAGIC    0410       /* read-only text */
           #define  ZMAGIC    0413       /* demand load format */

>  -n, --nmagic     Make text readonly, page align data, no demand paging

Should something else be changed, rather than change --nmagic to behave
differently from other architectures?

(Why isn't --no-omagic named --zmagic ? :)

Re: Help text for ld magic number options

[Stephen Casner]

On Sun, 23 Feb 2020, Fangrui Song wrote:

> On 2020-02-22, Stephen Casner wrote:
> > Thanks, Alan, for addressing bug 25569 more thoroughly than I would be
> > able to do.
> >
> > To all, next I have three proposed changes related to the magic number
> > options for ld on which I solicit your feedback.  First a simple one.
> >
> > The output of ld --help includes the following:
> >
> >  -n, --nmagic     Do not page align data
> >  -N, --omagic     Do not page align data, do not make text readonly
> >  --no-omagic      Page align data, make text readonly
> >
> > The help text for --nmagic is not accurate for the pdp11-aout target
> > and I believe not for others as well.  That option results in setting
> > config.text_read_only = TRUE, and in order to make the text read-only
> > the data must be aligned to a separate page on the PDP11 and I presume
> > for most if not all other computers as well.
> >
> > The references to page alignment really correspond to the setting of
> > config.magic_demand_paged which, when TRUE, selects the ZMAGIC (0413)
> > format in aoutx.h.  That format does require the data to be page
> > aligned, but more significantly it indicates to the runtime system to
> > do demand paging.  The pdp11-aout code in bfd/pdp11.c does not
> > implement the ZMAGIC format (even though there is some stub code for
> > it included when copying from aoutx.h) since demand paging isn't
> > practical on the PDP11 and wasn't implemented for it over the full
> > timespan from Unix v6 through 2.11 BSD.  Thus, for pdp11-aout the
> > options --no-omagic and --nmagic produce the same result.
> >
> > I propose that the help text be changed as follows:
> >
> >  -n, --nmagic     Make text readonly, page align data, no demand paging
> >  -N, --omagic     Do not make text readonly, do not page align data
> >  --no-omagic      Make text readonly, page align data, do demand paging
> >
> > Is that acceptable?  This would have implications for the ld
> > documentation as well.
> >
>
> http://man.cat-v.org/unix_10th/5/a.out
>
>           #define  OMAGIC    0407       /* old impure format */
>           #define  NMAGIC    0410       /* read-only text */
>           #define  ZMAGIC    0413       /* demand load format */
>
> >  -n, --nmagic     Make text readonly, page align data, no demand paging
>
> Should something else be changed, rather than change --nmagic to behave
> differently from other architectures?

In my proposed change above, I'm not suggesting any change in the
behavior of --nmagic.  The current behavior is correct and consistent
with the defines that you referenced.

I'm just pointing out that the help text (and the associated info
documentation) does not match the current behavior.  I mention the
PDP11 architecture because I know the help text is wrong for that
architecture.  I think it is also wrong for all the others, but I'm
ready to be challenged on that belief.

The help text for --nmagic says "Do not page align data" but --nmagic
is supposed to have read-only text, as shown by the comment of the
NMAGIC define you quote.  In order to have read-only text it is
necessary to align the data to a separate page from the text so the
data can be read-write.  So correct help text for --nmagic should
include "Do page align data".

> (Why isn't --no-omagic named --zmagic ? :)

I have no idea.  Is the author of that change still available?

                                                        -- Steve

Re: Help text for ld magic number options

[Andreas Schwab]

On Feb 22 2020, Stephen Casner wrote:

> I propose that the help text be changed as follows:
>
>   -n, --nmagic     Make text readonly, page align data, no demand paging
>   -N, --omagic     Do not make text readonly, do not page align data
>   --no-omagic      Make text readonly, page align data, do demand paging
>
> Is that acceptable?  This would have implications for the ld
> documentation as well.

I think there is some confusion about what "alignment" means in this
context.  Here is what the manpage says:

	       OMAGIC  The text	and data segments immediately follow the
		       header and are contiguous.  The kernel loads both text
		       and data	segments into writable memory.

	       NMAGIC  As with OMAGIC, text and	data segments immediately fol-
		       low the header and are contiguous.  However, the	kernel
		       loads the text into read-only memory and	loads the data
		       into writable memory at the next	page boundary after
		       the text.

	       ZMAGIC  The kernel loads	individual pages on demand from	the
		       binary.	The header, text segment and data segment are
		       all padded by the link editor to	a multiple of the page
		       size.  Pages that the kernel loads from the text	seg-
		       ment are	read-only, while pages from the	data segment
		       are writable.

The alignment appears to refer to the padding added by the link editor
in the ZMAGIC format.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: Help text for ld magic number options

[Stephen Casner]

On Mon, 24 Feb 2020, Andreas Schwab wrote:

> On Feb 22 2020, Stephen Casner wrote:
>
> > I propose that the help text be changed as follows:
> >
> >   -n, --nmagic     Make text readonly, page align data, no demand paging
> >   -N, --omagic     Do not make text readonly, do not page align data
> >   --no-omagic      Make text readonly, page align data, do demand paging
> >
> > Is that acceptable?  This would have implications for the ld
> > documentation as well.
>
> I think there is some confusion about what "alignment" means in this
> context.  Here is what the manpage says:
>
> 	       OMAGIC  The text	and data segments immediately follow the
> 		       header and are contiguous.  The kernel loads both text
> 		       and data	segments into writable memory.
>
> 	       NMAGIC  As with OMAGIC, text and	data segments immediately fol-
> 		       low the header and are contiguous.  However, the	kernel
> 		       loads the text into read-only memory and	loads the data
> 		       into writable memory at the next	page boundary after
> 		       the text.
>
> 	       ZMAGIC  The kernel loads	individual pages on demand from	the
> 		       binary.	The header, text segment and data segment are
> 		       all padded by the link editor to	a multiple of the page
> 		       size.  Pages that the kernel loads from the text	seg-
> 		       ment are	read-only, while pages from the	data segment
> 		       are writable.
>
> The alignment appears to refer to the padding added by the link editor
> in the ZMAGIC format.

Thanks for that clarification.  I think "padding" would be the more
operative word than "alignment" here, noting that the latter word does
not appear in the cited paragraphs.

How about:

   -n, --nmagic     Text in readonly pages, not padded for demand paging
   -N, --omagic     Do not make text readonly, do not page align data
   --no-omagic      Make text readonly, align and pad for demand paging

In both my original proposal and this one, the --no-omagic description
is inaccurate for the pdp11-aout format because padding to page
boundaries is never done, but there isn't a way to omit the common
options for some emulations.

                                                        -- Steve