[RFC PATCH] gas: correct .bss documentation for non-ELF

[RFC PATCH] gas: correct .bss documentation for non-ELF

[Jan Beulich]

Only ELF permits the specification of a subsection.
---
Except for H8 this doesn't look to have any effect, because all.texi
blindly enables various object formats. Yet still the documentation ends
up wrong for non-ELF targets.

--- a/gas/doc/as.texi
+++ b/gas/doc/as.texi
@@ -4456,7 +4456,12 @@ Some machine configurations provide addi
 * Asciz::                       @code{.asciz "@var{string}"}@dots{}
 * Attach_to_group::             @code{.attach_to_group @var{name}}
 * Balign::                      @code{.balign [@var{abs-expr}[, @var{abs-expr}]]}
+@ifset ELF
 * Bss::                         @code{.bss @var{subsection}}
+@end ifset
+@ifclear ELF
+* Bss::                         @code{.bss}
+@end ifclear
 * Bundle directives::           @code{.bundle_align_mode @var{abs-expr}}, etc
 * Byte::                        @code{.byte @var{expressions}}
 * CFI directives::		@code{.cfi_startproc [simple]}, @code{.cfi_endproc}, etc.
@@ -4801,8 +4806,14 @@ filled in with the value 0x368d (the exa
 the endianness of the processor).  If it skips 1 or 3 bytes, the fill value is
 undefined.
 
+@ifset ELF
 @node Bss
 @section @code{.bss @var{subsection}}
+@end ifset
+@ifclear ELF
+@node Bss
+@section @code{.bss}
+@end ifclear
 @cindex @code{bss} directive
 
 @code{.bss} tells @command{@value{AS}} to assemble the following statements

Re: [RFC PATCH] gas: correct .bss documentation for non-ELF

[Nick Clifton]

Hi Jan,

> Only ELF permits the specification of a subsection.

Patch approved - obviously.

> Except for H8 this doesn't look to have any effect, because all.texi
> blindly enables various object formats. Yet still the documentation ends
> up wrong for non-ELF targets.

Although the text in the node does mention that subsections are only
support for ELF based targets.

One question:

> +@ifset ELF
>   @node Bss
>   @section @code{.bss @var{subsection}}
> +@end ifset
> +@ifclear ELF
> +@node Bss
> +@section @code{.bss}
> +@end ifclear
>   @cindex @code{bss} directive

Does the texi format care that there are two instances of "@node Bss" ?
I assume not and that you have tested it.  It just seemed a little counter
intuitive to me.  I would have thought:

   @node Bss
   @ifset ELF
   @section @code{.bss @var{subsection}}
   @end ifset
   @ifclear ELF
   @section @code{.bss}
   @end ifclear

Would be a slightly simpler arrangement.  Not that it matters really.

Cheers
   Nick

Re: [RFC PATCH] gas: correct .bss documentation for non-ELF

[Jan Beulich]

On 27.11.2023 12:27, Nick Clifton wrote:
>> Only ELF permits the specification of a subsection.
> 
> Patch approved - obviously.
> 
>> Except for H8 this doesn't look to have any effect, because all.texi
>> blindly enables various object formats. Yet still the documentation ends
>> up wrong for non-ELF targets.
> 
> Although the text in the node does mention that subsections are only
> support for ELF based targets.

Right. That was one half of the reason for sending this as RFC. The other
was the very limited effect this change has in reality (as mentioned above).

> One question:
> 
>> +@ifset ELF
>>   @node Bss
>>   @section @code{.bss @var{subsection}}
>> +@end ifset
>> +@ifclear ELF
>> +@node Bss
>> +@section @code{.bss}
>> +@end ifclear
>>   @cindex @code{bss} directive
> 
> Does the texi format care that there are two instances of "@node Bss" ?
> I assume not and that you have tested it.  It just seemed a little counter
> intuitive to me.  I would have thought:
> 
>    @node Bss
>    @ifset ELF
>    @section @code{.bss @var{subsection}}
>    @end ifset
>    @ifclear ELF
>    @section @code{.bss}
>    @end ifclear
> 
> Would be a slightly simpler arrangement.  Not that it matters really.

That's how I had it initially, until a broken build quickly told me it
needs to be the redundant way for at least some version of some of the
tools processing this file as input.

Jan

Re: [RFC PATCH] gas: correct .bss documentation for non-ELF

[Jan Beulich]

On 27.11.2023 12:27, Nick Clifton wrote:
>> Only ELF permits the specification of a subsection.
> 
> Patch approved - obviously.

Actually I'm going to hold off committing this until I have a complete
view on the ELF situation. As it stands, not all targets allow the
subsection specification. Yet then for some of the targets I looked at
their overriding of .bss is bogus in the first place (and breaking
.previous in at least some of the cases), and hence I am queuing
patches to remove some of those overrides. Only once done I will know
whether the ELF part of the documentation will also need adjusting to
actually say "most ELF targets" or "some ELF targets" or alike.

Jan