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

[H.J. Lu]

On Thu, Jan 16, 2020 at 7:14 AM Jan Beulich <jbeulich@suse.com> wrote:
>
> On 16.01.2020 15:57,  H.J. Lu  wrote:
> > On Thu, Jan 16, 2020 at 1:16 AM Jan Beulich <jbeulich@suse.com> wrote:
> >>
> >> 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.
> >
> > It should say how to use your new far branches.
>
> H.J., please. You keep saying this in varying wording, without it
> becoming any more clear to me what you're after. Again - can you
> point me to some existing piece of documentation where such "how
> to use" is already being described, for some earlier addition (or
> even some basic insns)? I'm not very good at writing documentation,
> and I'm doing even less good with guessing what is wanted. Hence my
> request to have at least something to start from.
>
> I've also taken a look at two somewhat similar changes of yours
> (07f5af7d3c63 "Handle indirect branches for AMD64 and Intel64" and
> 5db04b0965e3 "Support AMD64/Intel ISAs in assembler/disassembler"),
> which didn't contain any [respective] doc updates.
>

We should improve gas documentation.  The current far branches
work fine.  Why bother to add new far branches without giving
developer a clue how to use them?

-- 
H.J.