[v2,4/7] ld.texi: Add ASCII to info file

Message ID 20240705162248.24954-5-binutils@emagii.com
State New
Headers
Series ASCII output section command |

Checks

Context Check Description
linaro-tcwg-bot/tcwg_binutils_build--master-arm success Build passed
linaro-tcwg-bot/tcwg_binutils_build--master-aarch64 success Build passed
linaro-tcwg-bot/tcwg_binutils_check--master-aarch64 success Test passed
linaro-tcwg-bot/tcwg_binutils_check--master-arm success Test passed

Commit Message

Ulf Samuelsson July 5, 2024, 4:22 p.m. UTC
  From: Ulf Samuelsson <ulf@emagii.com>

Signed-off-by: Ulf Samuelsson <ulf@emagii.com>
---
 ld/ld.texi | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)
  

Comments

Jan Beulich July 8, 2024, 6:23 a.m. UTC | #1
On 05.07.2024 18:22, binutils@emagii.com wrote:
> --- a/ld/ld.texi
> +++ b/ld/ld.texi
> @@ -5643,6 +5643,7 @@ C identifiers because they contain a @samp{.} character.
>  @cindex section data
>  @cindex output section data
>  @kindex ASCIZ ``@var{string}''
> +@kindex ASCII (@var{expression}) ``@var{string}''

I couldn't really spot anywhere you would say what has changed from the
earlier version, so I'm unsure: Are, as per above, parentheses still
required here, or ...

> @@ -5691,6 +5692,28 @@ For example, this string of 16 characters will create a 17 byte area
>    ASCIZ "This is 16 bytes"
>  @end smallexample
>  
> +You can include a fixed size string in an output section by using
> +@code{ASCII}.  The keyword is followed by a size and a string
> +separated by a comma.  The string is stored at the current
> +value of the location counter. If the string is shorted than the allocated
> +size, NUL character are added at the end to fill up to the specified size.
> +Note the fill value is ignored for this padding.
> +If the string includes spaces it must be enclosed in double
> +quotes.  The string may contain '\n', '\r', '\t' and octal numbers.
> +Hex numbers are not supported.
> +
> +If the string is too long, a warning is issued and the string is
> +truncated.  The string will still be zero-terminated in this case.
> +
> +If the expression evaluates to zero then the directive will be treated
> +as if it were @code{ASCIZ} instead.
> +
> +Example: This is string of 16 characters and will create a 16 byte
> +area, not zero-terminated.
> +@smallexample
> +  ASCII 16, "This is 16 bytes"
> +@end smallexample

... are they not anymore, as per this and the cover letter?

Jan
  
Ulf Samuelsson July 8, 2024, 10:59 a.m. UTC | #2
Den 2024-07-08 kl. 08:23, skrev Jan Beulich:
> On 05.07.2024 18:22, binutils@emagii.com wrote:
>> --- a/ld/ld.texi
>> +++ b/ld/ld.texi
>> @@ -5643,6 +5643,7 @@ C identifiers because they contain a @samp{.} character.
>>   @cindex section data
>>   @cindex output section data
>>   @kindex ASCIZ ``@var{string}''
>> +@kindex ASCII (@var{expression}) ``@var{string}''
> I couldn't really spot anywhere you would say what has changed from the
> earlier version, so I'm unsure: Are, as per above, parentheses still
> required here, or ...
>
>> @@ -5691,6 +5692,28 @@ For example, this string of 16 characters will create a 17 byte area
>>     ASCIZ "This is 16 bytes"
>>   @end smallexample
>>   
>> +You can include a fixed size string in an output section by using
>> +@code{ASCII}.  The keyword is followed by a size and a string
>> +separated by a comma.  The string is stored at the current
>> +value of the location counter. If the string is shorted than the allocated
>> +size, NUL character are added at the end to fill up to the specified size.
>> +Note the fill value is ignored for this padding.
>> +If the string includes spaces it must be enclosed in double
>> +quotes.  The string may contain '\n', '\r', '\t' and octal numbers.
>> +Hex numbers are not supported.
>> +
>> +If the string is too long, a warning is issued and the string is
>> +truncated.  The string will still be zero-terminated in this case.
>> +
>> +If the expression evaluates to zero then the directive will be treated
>> +as if it were @code{ASCIZ} instead.
>> +
>> +Example: This is string of 16 characters and will create a 16 byte
>> +area, not zero-terminated.
>> +@smallexample
>> +  ASCII 16, "This is 16 bytes"
>> +@end smallexample
> ... are they not anymore, as per this and the cover letter?
>
> Jan

I changed it from

ASCII '(' <size> ')' <string>

to

ASCII <size> ',' <string>
  

Patch

diff --git a/ld/ld.texi b/ld/ld.texi
index 89e3913317a..7f86de5452d 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -5643,6 +5643,7 @@  C identifiers because they contain a @samp{.} character.
 @cindex section data
 @cindex output section data
 @kindex ASCIZ ``@var{string}''
+@kindex ASCII (@var{expression}) ``@var{string}''
 @kindex BYTE(@var{expression})
 @kindex SHORT(@var{expression})
 @kindex LONG(@var{expression})
@@ -5681,7 +5682,7 @@  endianness of the first input object file.
 
 You can include a zero-terminated string in an output section by using
 @code{ASCIZ}.  The keyword is followed by a string which is stored at
-the current value of the location counter adding a zero byte at the
+the current value of the location counter adding a NUL byte at the
 end.  If the string includes spaces it must be enclosed in double
 quotes.  The string may contain '\n', '\r', '\t' and octal numbers.
 Hex numbers are not supported.
@@ -5691,6 +5692,28 @@  For example, this string of 16 characters will create a 17 byte area
   ASCIZ "This is 16 bytes"
 @end smallexample
 
+You can include a fixed size string in an output section by using
+@code{ASCII}.  The keyword is followed by a size and a string
+separated by a comma.  The string is stored at the current
+value of the location counter. If the string is shorted than the allocated
+size, NUL character are added at the end to fill up to the specified size.
+Note the fill value is ignored for this padding.
+If the string includes spaces it must be enclosed in double
+quotes.  The string may contain '\n', '\r', '\t' and octal numbers.
+Hex numbers are not supported.
+
+If the string is too long, a warning is issued and the string is
+truncated.  The string will still be zero-terminated in this case.
+
+If the expression evaluates to zero then the directive will be treated
+as if it were @code{ASCIZ} instead.
+
+Example: This is string of 16 characters and will create a 16 byte
+area, not zero-terminated.
+@smallexample
+  ASCII 16, "This is 16 bytes"
+@end smallexample
+
 Note---these commands only work inside a section description and not
 between them, so the following will produce an error from the linker:
 @smallexample