Re: [PATCH 0/7] tcg: Document *swap/deposit helpers

["Philippe Mathieu-Daudé" <philmd@linaro.org>]

On 22/8/23 15:42, Alex Bennée wrote:
> 
> Philippe Mathieu-Daudé <philmd@linaro.org> writes:
> 
>> While reviewing a recent patch from Richard optimizing
>> deposit() [*] I ended looking at the *swap friends, taking
>> some notes, which then evolved to proper documentation.
>>
>> [*]
>> https://lore.kernel.org/qemu-devel/20230816145547.477974-3-richard.henderson@linaro.org/
> 
> We already have some documentation in tcg.rst:
> 
>     * - bswap16_i32/i64 *t0*, *t1*, *flags*
> 
>       - | 16 bit byte swap on the low bits of a 32/64 bit input.
>         |
>         | If *flags* & ``TCG_BSWAP_IZ``, then *t1* is known to be zero-extended from bit 15.
>         | If *flags* & ``TCG_BSWAP_OZ``, then *t0* will be zero-extended from bit 15.
>         | If *flags* & ``TCG_BSWAP_OS``, then *t0* will be sign-extended from bit 15.
>         |
>         | If neither ``TCG_BSWAP_OZ`` nor ``TCG_BSWAP_OS`` are set, then the bits of *t0* above bit 15 may contain any value.
> 
>     * - bswap32_i64 *t0*, *t1*, *flags*
> 
>       - | 32 bit byte swap on a 64-bit value.  The flags are the same as for bswap16,
>           except they apply from bit 31 instead of bit 15.
> 
>     * - bswap32_i32 *t0*, *t1*, *flags*
> 
>         bswap64_i64 *t0*, *t1*, *flags*
> 
>       - | 32/64 bit byte swap. The flags are ignored, but still present
>           for consistency with the other bswap opcodes.

I guess I wasn't clear enough: I mostly documented the implementation,
not the API.

That said, maybe the bytes movement pattern belong to the API doc
(at least I find it very useful to find which TCG opcode implement
the frontend code, when the TCG opcode name isn't trivial, although
documented).