[doc]Added examples for generic opcodes

[pooja2299]

Summary

Added examples to G_BR, G_BRCOND, G_BRJT, G_BRINDIRECT

[xgupta]

I would suggest you to take your full time, understand Generic Machine IR thoroughly i.e. know the meaning of every letter in the testcases from where you taken these examples. And then write more descriptive Opcode docs something like as LLVM IR instruction reference https://llvm.org/docs/LangRef.html#instruction-reference.

llvm/docs/GlobalISel/GenericOpcode.rst

768

why 1 not 0 or 2?

776

Why 4 not 3 or 5 or maybe 0?

[pooja2299]

In D104974#2842785, @xgupta wrote:

I would suggest you to take your full time, understand Global Machine IR thoroughly i.e. know the meaning of every letter in the testcases from where you taken these examples. And then write more descriptive Opcode docs something like as LLVM IR instruction reference https://llvm.org/docs/LangRef.html#instruction-reference.

Ok will do that . Since there are short descriptions provided for the Generic opcodes, I thought I have to write short descriptions.

llvm/docs/GlobalISel/GenericOpcode.rst

768

Since other Generic opcodes had examples with mentioning specific registers, I also took an example similar to that . For eg: the example of G_PHI

[xgupta]

Ok will do that . Since there are short descriptions provided for the Generic opcodes, I thought I have to write short descriptions.

I think more description will be better, beginner may find it difficult to understand without details.
Active developers might have more thoughts on how much you should extend it :)

[pooja2299]

In D104974#2842800, @xgupta wrote:

Ok will do that . Since there are short descriptions provided for the Generic opcodes, I thought I have to write short descriptions.

I think more description will be better, beginner may find it difficult to understand without details.
Active developers might have more thoughts on how much you should extend it :)

okk. @paquette @aemerson @arsenm @gandhi21299 @kbarton looking forward for your suggestions.

[paquette]

I think that @xgupta's suggestions are a good idea. I would recommend changing any unnamed vregs (e.g. %0, %2, etc.) to named values.

llvm/include/llvm/Target/GenericOpcodes.td has the source for these. There operand lists may have some more descriptive names that you can reuse. E.g.:

// Generic branch to jump table entry
def G_BRJT : GenericInstruction {
  let OutOperandList = (outs);
  let InOperandList = (ins ptype0:$tbl, unknown:$jti, type1:$idx);
  let hasSideEffects = false;
  let isBranch = true;
  let isTerminator = true;
  let isBarrier = true;
  let isIndirectBranch = true;
}

The input names here aren't super descriptive, but they give a better hint than what we have right now.

Ultimately, I think it would be nice if the documentation was written in this style:

G_ADD
^^^^^^

Adds %src1 to %src0 and stores the result in %dst.

.. code-block:: none

  %dst:_(s32) = G_ADD %src0:_(s32), %src1:_(s32)

llvm/docs/GlobalISel/GenericOpcode.rst

784

792

We could add more descriptive names here, like @xgupta suggested.

I just copied these from GenericOpcodes.td. (Although I changed "$tbl" to "ptr" here because I think that's more beginner-friendly.)

[pooja2299]

In D104974#2844469, @paquette wrote:

I think that @xgupta's suggestions are a good idea. I would recommend changing any unnamed vregs (e.g. %0, %2, etc.) to named values.

llvm/include/llvm/Target/GenericOpcodes.td has the source for these. There operand lists may have some more descriptive names that you can reuse. E.g.:

// Generic branch to jump table entry
def G_BRJT : GenericInstruction {
  let OutOperandList = (outs);
  let InOperandList = (ins ptype0:$tbl, unknown:$jti, type1:$idx);
  let hasSideEffects = false;
  let isBranch = true;
  let isTerminator = true;
  let isBarrier = true;
  let isIndirectBranch = true;
}

The input names here aren't super descriptive, but they give a better hint than what we have right now.

Thanks a lot! This was very helpful.

[pooja2299]

In D104974#2844469, @paquette wrote:

Ultimately, I think it would be nice if the documentation was written in this style:

G_ADD
^^^^^^

Adds %src1 to %src0 and stores the result in %dst.

.. code-block:: none

  %dst:_(s32) = G_ADD %src0:_(s32), %src1:_(s32)

Ok, I will keep this in mind.

[aemerson]

llvm/docs/GlobalISel/GenericOpcode.rst

768

why 1 not 0 or 2?

We actually begin our block numbering at 1.

776

I suggest %cond or %condition for this

[arsenm]

llvm/docs/GlobalISel/GenericOpcode.rst

768

This isn't true, there's just currently some oddity that ends up emitting an extra block in IRTranslator

[xgupta]

reverse ping @pooja2299

[pooja2299]

llvm/docs/GlobalISel/GenericOpcode.rst

776

ok thanks @aemerson

792

Sure, I will change the unamed vregs to more descriptive names.

[pooja2299]

Updated with descriptive names of vregs.

[pooja2299]

In D104974#2857496, @xgupta wrote:

reverse ping @pooja2299

sorry ...I have replied to inline comments week before but forgot to click the 'submit' button below. New to phabricator ..so keep on forgetting these small things. 😅

Will be updating other changes soon.

[paquette]

llvm/docs/GlobalISel/GenericOpcode.rst

293–295

minor typo

760

Might was well rename the vregs here too. :)

[pooja2299]

Edited name of vregs in the given examples

[paquette]

llvm/docs/GlobalISel/GenericOpcode.rst

295

I suggest to make it clear that this sentence references the given example.

[pooja2299]

llvm/docs/GlobalISel/GenericOpcode.rst

295

Yes that would be precise, thanks for indicating it!

[pooja2299]

Updated the required changes for description of G_ADD

[paquette]

LGTM, thank you!

[pooja2299]

Thanks for reviewing this patch!

llvm/docs/GlobalISel/GenericOpcode.rst

 
 G_ADD, G_SUB, G_MUL, G_AND, G_OR, G_XOR, G_SDIV, G_UDIV, G_SREM, G_UREM
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 These each perform their respective integer arithmetic on a scalar.
 
 .. code-block:: none
 
-  %2:_(s32) = G_ADD %0:_(s32), %1:_(s32)
+  %dst:_(s32) = G_ADD %src0:_(s32), %src1:_(s32)
+
+The above exmaple adds %src1 to %src0 and stores the result in %dst.
 
 G_SDIVREM, G_UDIVREM
 ^^^^^^^^^^^^^^^^^^^^
 
 Perform integer division and remainder thereby producing two results.
 
 .. code-block:: none
 

 
 G_PHI
 ^^^^^
 
 Implement the φ node in the SSA graph representing the function.
 
 .. code-block:: none
 
-  %1(s8) = G_PHI %7(s8), %bb.0, %3(s8), %bb.1
+  %dst(s8) = G_PHI %src1(s8), %bb.<id1>, %src2(s8), %bb.<id2>
 
 G_BR
 ^^^^
 
 Unconditional branch
 
+.. code-block:: none
+  G_BR %bb.<id>
+
 G_BRCOND
 ^^^^^^^^
 
 Conditional branch
 
+.. code-block:: none
+  G_BRCOND %condition, %basicblock.<id>
+
 G_BRINDIRECT
 ^^^^^^^^^^^^
 
 Indirect branch
 
+.. code-block:: none
+  G_BRINDIRECT %src(p0)
+
 G_BRJT
 ^^^^^^
 
 Indirect branch to jump table entry
 
+.. code-block:: none
+  G_BRJT %ptr(p0), %jti, %idx(s64)
+
 G_JUMP_TABLE
 ^^^^^^^^^^^^
 
 .. caution::
 
   I found no documentation for this instruction at the time of writing.
 
 G_INTRINSIC, G_INTRINSIC_W_SIDE_EFFECTS