[Docs] Add tablegen backend for target opcode documentatio
ClosedPublic

Authored by olista01 on Mar 16 2017, 2:47 AM.

Details

Summary

This is a tablegen backend to generate documentation for the opcodes that exist for each target. For each opcode, it lists the assembly string, the names and types of all operands, and the flags and predicates that apply to the opcode.

As far as I can tell, the current table-generated documentation is built for llvm.org by some method external to the CMake scripts. What need doing to get this documentation visible on llvm.org?

Diff Detail

Repository
rL LLVM
olista01 created this revision.Mar 16 2017, 2:47 AM
bjope added a subscriber: bjope.Mar 16 2017, 2:08 PM

I wanted to look at the documentation produced for a specific instruction today, as part of investigation PR35157.
I wanted to understand what the operands of VST1d64TPseudoWB_fixed are in the Arm backend.
After downloading this patch and building/running it; I saw it produced the following documentation for that instruction:

VST1d64TPseudoWB\_fixed
=======================

Flags: ``mayStore``, ``isPredicable``, ``hasExtraSrcRegAllocReq``, ``isCodeGenOnly``

* DEF ``GPR:$wb``

* USE ``addrmode6:$addr`` (**tied to wb**)

* USE ``QQPR:$src``

* USE ``pred:$p``

Predicates: ``HasNEON``

However, this doesn't seem to print all of the operands. It seemingly only prints the operands that are represented somehow in the assembly representation of the instruction?
When looking in ARMGenInstrInfo.inc, for the same instruction, I find (after formatting and adding a few comments to improve readability):

  { 2209,
    /*NumOperands*/     6,
    /*NumDefs*/ 1,
    /*Size*/    4,
    /*SchedClass*/      646,
    /*Flags*/   0|(1ULL<<MCID::MayStore)|(1ULL<<MCID::Predicable)|(1ULL<<MCID::ExtraSrcRegAllocReq),
    /*TSFlags*/ 0x10006ULL,
    /*ImplicitUses*/ nullptr,
    /*ImplicitDefs*/ nullptr,
    /*MCOperandInfo* */OperandInfo275,
    /*DeprecatedFeature*/ -1 ,
    /*?*/ nullptr },  // Inst #2209 = VST1d64TPseudoWB_fixed
....
static const MCOperandInfo OperandInfo275[] = {
  { ARM::GPRRegClassID, 0, MCOI::OPERAND_REGISTER, 0 },
  { ARM::GPRRegClassID, 0, MCOI::OPERAND_MEMORY, ((0 << 16) | (1 << MCOI::TIED_TO)) },
  { -1, 0, MCOI::OPERAND_MEMORY, 0 },
  { ARM::QQPRRegClassID, 0, MCOI::OPERAND_REGISTER, 0 },
  { -1, 0|(1<<MCOI::Predicate), MCOI::OPERAND_UNKNOWN, 0 },
  { -1, 0|(1<<MCOI::Predicate), MCOI::OPERAND_UNKNOWN, 0 },
};

This shows the instruction has 6 operands, 2 more than the 4 operands printed in the documentation.
Could the output in the documentation be adapted so that it prints all operands?

asb added a subscriber: asb.Wed, Nov 8, 8:32 AM
olista01 updated this revision to Diff 122233.Thu, Nov 9, 6:10 AM
olista01 added reviewers: rovka, MatzeB.

Instead of only printing the operands that appear in the assembly string (some of which correspond to more then one MachineOperand), print a flattened list of operands. Kristof's example instruction now generates this documentation:

VST1d64TPseudoWB\_fixed
=======================

Flags: ``mayStore``, ``isPredicable``, ``hasExtraSrcRegAllocReq``, ``isCodeGenOnly``

* DEF ``GPR:$wb``

* USE ``addrmode6/GPR:$addr.addr``

* USE ``addrmode6/i32imm:$addr.align``

* USE ``QQPR:$src``

* USE ``pred/i32imm:$p.anon0``

* USE ``pred/i32imm:$p.anon1``

Constraints: ``$addr.addr = $wb``

Predicates: ``HasNEON``
kristof.beyls accepted this revision.Tue, Nov 14, 6:56 AM

LGTM, modulo the one comment about the file header.

utils/TableGen/InstrDocsEmitter.cpp
1–7 ↗(On Diff #122233)

This new file needs a header.

52–54 ↗(On Diff #122233)

It's probably debatable whether it's useful or not to also print documentation for the target-independent instructions. But let's leave this as is for now.

This revision is now accepted and ready to land.Tue, Nov 14, 6:56 AM
This revision was automatically updated to reflect the committed changes.