Hi Carl,
on 2024/6/27 01:05, Carl Love wrote:
> GCC maintainers:
>
> The following patch updates the user documentation for the vec_ld, vec_lde,
> vec_st and vec_ste built-ins to make it clearer that there are data alignment
> requirements for these built-ins. If the data alignment requirements are not
> followed, the data loaded or stored by these built-ins will be wrong.
>
> Please let me know if this patch is acceptable for mainline. Thanks.
>
> Carl
>
> ----------------------------------------------------
> rs6000, update vec_ld, vec_lde, vec_st and vec_ste documentation
>
> Use of the vec_ld and vec_st built-ins require that the data be 16-byte
> aligned to work properly. Add some additional text to the existing
> documentation to make this clearer to the user.
>
> Similarly, the vec_lde and vec_ste built-ins also have data alignment
> requirements based on the size of the vector element. Update the
> documentation to make this clear to the user.
>
> gcc/ChangeLog:
> * doc/extend.texi: Add clarification for the use of the vec_ld
> vec_st, vec_lde and vec_ste built-ins.
> ---
> gcc/doc/extend.texi | 15 +++++++++++----
> 1 file changed, 11 insertions(+), 4 deletions(-)
>
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index ee3644a5264..55faded17b9 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -22644,10 +22644,17 @@ vector unsigned char vec_xxsldi (vector unsigned
> char,
> @end smallexample
>
> Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
> -generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
> -if the VSX instruction set is available. The @samp{vec_vsx_ld} and
> -@samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
> -@samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
> +generate the AltiVec @samp{LVX}, and @samp{STVX} instructions. The
This change removed "even if the VSX instruction set is available.", I think
it's
not intentional? vec_ld and vec_st are well defined in PVIPR, this paragraph is
not to document them IMHO. Since we document vec_vsx_ld and vec_vsx_st here, it
aims to note the difference between these two pairs. But I'm not opposed to add
more words to emphasis the special masking off, I prefer to use the same words
to
PVIPR "ignoring the four low-order bits of the calculated address". And IMHO we
should not say "it requires the data to be 16-byte aligned to work properly" in
case the users are aware of this behavior well and have some no 16-byte aligned
data and expect it to behave like that, it's arguable to define "it" as not work
properly.
> +instructions mask off the lower 4 bits of the effective address thus
> requiring
> +the data to be 16-byte aligned to work properly. The @samp{vec_lde} and
> +@samp{vec_ste} built-in functions operate on vectors of bytes, short integer,
> +integer, and float. The corresponding AltiVec instructions @samp{LVEBX},
> +@samp{LVEHX}, @samp{LVEWX}, @samp{STVEBX}, @samp{STVEHX}, @samp{STVEWX} mask
> +off the lower bits of the effective address based on the size of the data.
> +Thus the data must be aligned to the size of the vector element to work
> +properly. The @samp{vec_vsx_ld} and @samp{vec_vsx_st} built-in functions
> +always generate the VSX @samp{LXVD2X}, @samp{LXVW4X}, @samp{STXVD2X}, and
> +@samp{STXVW4X} instructions.
As above, there was a reason to mention vec_ld and vec_st here, but not one for
vec_lde and vec_ste IMHO, so let's not mention vec_lde and vec_ste here and
users
should read the description in PVIPR instead (it's more recommended).
BR,
Kewen
>
> @node PowerPC AltiVec Built-in Functions Available on ISA 2.07
> @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07
