Re: [PATCH v3 10/10] x86-64: Intel64 adjustments for insns dealing with far pointers

[Jan Beulich <jbeulich at suse dot com>]

On 15.01.2020 22:58, H.J. Lu wrote:
> On Wed, Jan 15, 2020 at 9:03 AM Jan Beulich <jbeulich@suse.com> wrote:
>> On 15.01.2020 14:28, H.J. Lu wrote:
>>> On Tue, Jan 14, 2020 at 11:49 PM Jan Beulich <jbeulich@suse.com> wrote:
>>>> On 14.01.2020 18:05, H.J. Lu wrote:
>>>>> We should document how new far pointer branches are used
>>>>> in Intel and AT&T syntax.
>>>>
>>>> I have no idea at all what you're after. Could you give me a
>>>> pointer to existing text I could use to clone or at least refer
>>>> to, which then also would give me a hint where in the docs I
>>>> should insert such a piece of information which - as said - I
>>>> don't think has a need to be there in the first place? Once
>>>> again
>>>> - usage is consistent with other insns (none of which have any
>>>>   such piece of documentation afaict),
>>>> - we shouldn't duplicate SDM / PM information.
>>>>
>>>
>>> The current assembler supports far pointer branches.  Your change
>>> added a new one.  You should document how it differs from the
>>> existing one.
>>
>> This
>>
>> @cindex return instructions, i386
>> @cindex i386 jump, call, return
>> @cindex return instructions, x86-64
>> @cindex x86-64 jump, call, return
>> @item
>> Immediate form long jumps and calls are
>> @samp{lcall/ljmp $@var{section}, $@var{offset}} in AT&T syntax; the
>> Intel syntax is
>> @samp{call/jmp far @var{section}:@var{offset}}.  Also, the far return
>> instruction
>> is @samp{lret $@var{stack-adjust}} in AT&T syntax; Intel syntax is
>> @samp{ret far @var{stack-adjust}}.
>>
>> and this
>>
>> @cindex jump instructions, i386
>> @cindex call instructions, i386
>> @cindex jump instructions, x86-64
>> @cindex call instructions, x86-64
>> Far call/jump instructions are @samp{lcall} and @samp{ljmp} in
>> AT&T syntax, but are @samp{call far} and @samp{jump far} in Intel
>> convention.
>>
>> is what I've been able to find. Neither covers - for existing
>> forms - what you ask for, so I'm still entirely unclear what
> 
> They do cover existing far branches, lcall and ljmp in AT&T syntax.
> Since you are adding new far call and jmp, how should they be used?

I'm not adding anything new. The existing text doesn't mention
suffixed versions (e.g. lcalll or ljmpw), so I don't see how
mentioning lcallq and ljmpq would fit, and what it is that would
specifically need saying.

I'm certainly fine with extending existing documentation to
cover new (sub-)cases. I'm not fine with being asked to add
something new without it being clear why, what, how, and
where.

Jan

>> form of documentation of what specific aspects you're after.
>> Sadly you didn't address my prior request to point me at
>> something that I could go from. I'm afraid if you want me to
>> do this, you'll need to be more specific. An alternative might
>> be for you to put together whatever you think needs documenting.
> 
>