RISC-V: Document the degree of position independence that medany affords

  The code generated by -mcmodel=medany is defined to be
position-independent, but is not guarnteed to function correctly when
linked into position-independent executables or libraries.  See the
recent discussion at the psABI specification [1] for more details.

[1]: https://github.com/riscv-non-isa/riscv-elf-psabi-doc/issues/245

gcc/ChangeLog:

	* doc/invoke.texi: Document the degree of position independence
	that -mcmodel=medany affords.

Signed-off-by: Palmer Dabbelt <palmer@rivosinc.com>
---
 gcc/doc/invoke.texi | 4 ++++
 1 file changed, 4 insertions(+)
  

On Fri, Jan 14, 2022 at 4:42 AM Palmer Dabbelt <palmer@rivosinc.com> wrote:
>
> The code generated by -mcmodel=medany is defined to be
> position-independent, but is not guarnteed to function correctly when
> linked into position-independent executables or libraries.  See the
> recent discussion at the psABI specification [1] for more details.
>
> [1]: https://github.com/riscv-non-isa/riscv-elf-psabi-doc/issues/245
>
> gcc/ChangeLog:
>
>         * doc/invoke.texi: Document the degree of position independence
>         that -mcmodel=medany affords.
>
> Signed-off-by: Palmer Dabbelt <palmer@rivosinc.com>
> ---
>  gcc/doc/invoke.texi | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 5504971ea81..eaba12bb61f 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -27568,6 +27568,10 @@ Generate code for the medium-any code model. The program and its statically
>  defined symbols must be within any single 2 GiB address range. Programs can be
>  statically or dynamically linked.
>
> +The code generated by the medium-any code model is position-independent, but is
> +not guarnteed to function correctly when linked into position-independent
> +executables or libraries.

Typo: guarnteed -> guaranteed

I think it would be more helpful from a user perspective if a hint to
the solution
(i.e. use -fPIC) would be there. What about something like this:
"""
The code generated by the medium-any code model is position-independent.
However, to link such code into position-independent executables or libraries,
the corresponding flags to enable position-independent code generation
still need to be provided (e.g. -fPIC or -fPIE).
"""

>  @item -mexplicit-relocs
>  @itemx -mno-exlicit-relocs
>  Use or do not use assembler relocation operators when dealing with symbolic
> --
> 2.32.0
  

On Thu, 13 Jan 2022 21:54:45 PST (-0800), gcc-patches@gcc.gnu.org wrote:
> On Fri, Jan 14, 2022 at 4:42 AM Palmer Dabbelt <palmer@rivosinc.com> wrote:
>>
>> The code generated by -mcmodel=medany is defined to be
>> position-independent, but is not guarnteed to function correctly when
>> linked into position-independent executables or libraries.  See the
>> recent discussion at the psABI specification [1] for more details.
>>
>> [1]: https://github.com/riscv-non-isa/riscv-elf-psabi-doc/issues/245
>>
>> gcc/ChangeLog:
>>
>>         * doc/invoke.texi: Document the degree of position independence
>>         that -mcmodel=medany affords.
>>
>> Signed-off-by: Palmer Dabbelt <palmer@rivosinc.com>
>> ---
>>  gcc/doc/invoke.texi | 4 ++++
>>  1 file changed, 4 insertions(+)
>>
>> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
>> index 5504971ea81..eaba12bb61f 100644
>> --- a/gcc/doc/invoke.texi
>> +++ b/gcc/doc/invoke.texi
>> @@ -27568,6 +27568,10 @@ Generate code for the medium-any code model. The program and its statically
>>  defined symbols must be within any single 2 GiB address range. Programs can be
>>  statically or dynamically linked.
>>
>> +The code generated by the medium-any code model is position-independent, but is
>> +not guarnteed to function correctly when linked into position-independent
>> +executables or libraries.
>
> Typo: guarnteed -> guaranteed

Thanks.  IDK why I still can't figure out how to spell that word ;)

> I think it would be more helpful from a user perspective if a hint to
> the solution
> (i.e. use -fPIC) would be there. What about something like this:
> """
> The code generated by the medium-any code model is position-independent.
> However, to link such code into position-independent executables or libraries,
> the corresponding flags to enable position-independent code generation
> still need to be provided (e.g. -fPIC or -fPIE).
> """

I'd tried to make this more detailed, but everything I came up with was 
too verbose.  What you've got reads well, but it's not entirely 
accurate:

* A lot  of distros are defaulting to PIE now and there's "-fpic" and 
  "-fpie", so it's really more of a  "maybe pass -fpic, -fpie, -fPIE or 
  -fPIC but definitely don't pass the -no versions of those" 
  requirement.
* The code sequences generated by medany (without any of those PIC/pie 
  options enabled) can be linked into position-independent executables, 
  it's just might not result in symbol addresses that resolve as 
  expected.

Given that those constraints are well documented elsewhere (the GCC 
documentation for the arguments, and the psABI threads for the 
compiler/linker thing) I don't think it's strictly necessary to include 
everything here.  The rest of these blurbs are pretty terse and require 
users to understand these non-local definitions, so it's certainly in 
line with what's there.

That said, I do think this one is pretty tricky (it certainly tricked 
me), so if you or someone else has a better way of describing the actual 
constraints directly here then I'm all ears -- I couldn't come up with 
anything, though.

[As an aside, when I had the -fPIC blurb in medany I'd also added it to 
medlow as it's exactly the same there, but that also seemed too 
verbose.]

>>  @item -mexplicit-relocs
>>  @itemx -mno-exlicit-relocs
>>  Use or do not use assembler relocation operators when dealing with symbolic
>> --
>> 2.32.0