[docs] Minor fixes to CodeGenerator docs

[JOE1994]

Summary

• Fix incorrect word usage: commutable => commutative
• Other changes are grammar fixes and minor improvements in phrasing

[JOE1994]

If this commit gets approved:

Since I do not have commit access, it would be great if the reviewer could land this commit for me.
Please use "Youngsuk Kim [e-mail]" to commit the change.

Thank you very much!

[DanielMcIntosh-IBM]

Line 422 needs to be fixed before I resign or approve this change, but I have a few comments and questions as well.

What was the motivation for this change?

Except for the change on line 619 to correct a mistake that was a little jarring to read, these changes seem to be mostly a matter of personal preference for how you would write this document (or maybe rigid imposition of English grammar rules like when to use "less" or "fewer"). I'm personally not a fan of trivial changes like this cluttering up the commit history since they make it harder to get useful output from commands like git blame.

I know my comments below probably come off a bit harsh, and I'll say in advance that's not how I meant them. If it weren't for the change on line 422 I probably would have just resigned as a reviewer, since I don't have enough experience to know what the general attitude in the community is towards tiny inconsequential changes like this. I'd gladly approve and commit this for you if it was just the change on line 619, but for the rest (excluding line 422) I'm going to need more justification. If they're important to you, I can resign after you've fixed line 422.

llvm/docs/CodeGenerator.rst

291

I don't think this actually improves anything, except maybe removing ambiguity with the other definition of commutable ("allowing regular commuting to and from work"). If anything I feel the existing wording reads better (whether the instruction ... accesses memory, whether the instruction ... is commutable reads better to me than whether the instruction ... is commutative). Unless I'm missing something, this is a matter of personal preference and not worthy of making a change for.

422

This dramatically changes the meaning - The current form implies a limitation on the X86 divide operation ("The x86 architecture cannot use any registers except EAX and EDX for the divide operation"), while the edited form describes a feature ("Unlike other architectures the x86 can do a 32-bit divide using nothing but the EAX and EDX registers!")

1108

This does change the meaning slightly. "Is not yet finished" would imply there is a 'finished' or completed state that it hasn't yet achieved. Compare a city's infrastructure to an early access video-game. A city's infrastructure is a perpetual work in progress - always getting improved upon, repaired, expanded, etc. but there's no 'finish line'. In contrast, the early access video game has a goal that it's trying to get to. It's not that everything stops after the finish line is crossed, just that before then, it's missing major features and can't be considered a complete product. Development might not even slow down after the full release, but there shouldn't be any more loose ends.

I don't know which is more accurate here, since I don't know enough about the CodeGenerator to comment, but going based on the rest of your changes, it seems like you might be removing this because you felt it was superfluous, and I don't agree.

[JOE1994]

llvm/docs/CodeGenerator.rst

291

Thank you for your comment. My understanding was that the term 'commutable' has only one definition ("allowing regular commuting to and from work"), so I was almost confident that this word was used here by mistake. If the term 'commutable' is already a frequently used term when discussing traits of operators/instructions, I'd be happy to get rid of this change.

422

I initially thought my change would make it more clear for the phrase to have the former meaning that you suggested.
Maybe it might not be the case.. I'll get rid of this change.

1108

I will keep this unchanged. Thank you for your comments.

[JOE1994]

@DanielMcIntosh-IBM Thank you so much for taking your time to review this patch.

I have to agree with you that patches like this don't add much value to the codebase and rather clobber up git blame/git log results.

I decided to close this patch entirely. Thanks again for your feedback.

[DanielMcIntosh-IBM]

llvm/docs/CodeGenerator.rst

291

It is a more rare usage/definition, but it is a valid use of it: https://www.collinsdictionary.com/dictionary/english/commutable and https://www.google.com/search?q=define+commutable (that particular search result is sourced from oxford languages)

[craig.topper]

llvm/docs/CodeGenerator.rst

291

The property flag this refers to is called MCID::Commutable. So it wouldn't make sense to change the documentation without changing that too.

llvm/docs/CodeGenerator.rst

 
 The ``TargetInstrInfo`` class
 -----------------------------
 
 The ``TargetInstrInfo`` class is used to describe the machine instructions
 supported by the target.  Descriptions define things like the mnemonic for
 the opcode, the number of operands, the list of implicit register uses and defs,
 whether the instruction has certain target-independent properties (accesses
-memory, is commutable, etc), and holds any target-specific flags.
+memory, is commutative, etc), and holds any target-specific flags.
 
 The ``TargetFrameLowering`` class
 ---------------------------------
 
 The ``TargetFrameLowering`` class is used to provide information about the stack
 frame layout of the target. It holds the direction of stack growth, the known
 stack alignment on entry to each function, and the offset to the local area.
 The offset to the local area is the offset from the stack pointer on function

 
 Fixed (preassigned) registers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 One important issue that the code generator needs to be aware of is the presence
 of fixed registers.  In particular, there are often places in the instruction
 stream where the register allocator *must* arrange for a particular value to be
 in a particular register.  This can occur due to limitations of the instruction
-set (e.g., the X86 can only do a 32-bit divide with the ``EAX``/``EDX``
+set (e.g., the X86 can do a 32-bit divide with only the ``EAX``/``EDX``
 registers), or external factors like calling conventions.  In any case, the
 instruction selector should emit code that copies a virtual register into or out
 of a physical register when needed.
 
 For example, consider this simple LLVM example:
 
 .. code-block:: llvm
 

 over all of the MIs in a MachineBasicBlock, including those which are nested
 inside bundles. The top level BUNDLE instruction must have the correct set of
 register MachineOperand's that represent the cumulative inputs and outputs of
 the bundled MIs.
 
 Packing / bundling of MachineInstrs for VLIW architectures should
 generally be done as part of the register allocation super-pass. More
 specifically, the pass which determines what MIs should be bundled
-together should be done after code generator exits SSA form
+together should be run after code generator exits SSA form
 (i.e. after two-address pass, PHI elimination, and copy coalescing).
 Such bundles should be finalized (i.e. adding BUNDLE MIs and input and
 output register MachineOperands) after virtual registers have been
 rewritten into physical registers. This eliminates the need to add
 virtual register operands to BUNDLE instructions which would
 effectively double the virtual register def and use lists. Bundles may
 use virtual registers and be formed in SSA form, but may not be
 appropriate for all use cases.
 
 .. _MC Layer:
 
 The "MC" Layer
 ==============
 
 The MC Layer is used to represent and process code at the raw machine code
 level, devoid of "high level" information like "constant pools", "jump tables",
 "global variables" or anything like that.  At this level, LLVM handles things
 like label names, machine instructions, and sections in the object file.  The
 code in this layer is used for a number of important purposes: the tail end of
 the code generator uses it to write a .s or .o file, and it is also used by the
 llvm-mc tool to implement standalone machine code assemblers and disassemblers.
 
 This section describes some of the important classes.  There are also a number
-of important subsystems that interact at this layer, they are described later in
+of important subsystems that interact at this layer, which are described later in
 this manual.
 
 .. _MCStreamer:
 
 The ``MCStreamer`` API
 ----------------------
 
 MCStreamer is best thought of as an assembler API.  It is an abstract API which
 is *implemented* in different ways (e.g. to output a .s file, output an ELF .o
-file, etc) but whose API correspond directly to what you see in a .s file.
+file, etc) but whose API corresponds directly to what you see in a .s file.
 MCStreamer has one method per directive, such as EmitLabel, EmitSymbolAttribute,
 switchSection, emitValue (for .byte, .word), etc, which directly correspond to
 assembly level directives.  It also has an EmitInstruction method, which is used
 to output an MCInst to the streamer.
 
 This API is most important for two clients: the llvm-mc stand-alone assembler is
 effectively a parser that parses a line, then invokes a method on MCStreamer. In
 the code generator, the `Code Emission`_ phase of the code generator lowers

 are defined in the ``include/llvm/Target/TargetSelectionDAG.td`` file.
 "``F4RC``" is the register class of the input and result values.
 
 The TableGen DAG instruction selector generator reads the instruction patterns
 in the ``.td`` file and automatically builds parts of the pattern matching code
 for your target.  It has the following strengths:
 
 * At compiler-compile time, it analyzes your instruction patterns and tells you
-  if your patterns make sense or not.
+  whether your patterns make sense or not.
 
 * It can handle arbitrary constraints on operands for the pattern match.  In
   particular, it is straight-forward to say things like "match any immediate
   that is a 13-bit sign-extended value".  For examples, see the ``immSExt16``
   and related ``tblgen`` classes in the PowerPC backend.
 
 * It knows several important identities for the patterns defined.  For example,
   it knows that addition is commutative, so it allows the ``FMADDS`` pattern
* When using the 'Pat' class to map a pattern to an instruction that has one
   Here, the pair of ``ptroff`` and ``ptrreg`` operands is matched onto the
   complex operand ``dst`` of class ``memri`` in the ``STWU`` instruction.
 
 * While the system does automate a lot, it still allows you to write custom C++
   code to match special cases if there is something that is hard to
   express.
 
 While it has many strengths, the system currently has some limitations,
-primarily because it is a work in progress and is not yet finished:
+primarily because it is a work in progress:
 
 * Overall, there is no way to define or match SelectionDAG nodes that define
   multiple values (e.g. ``SMUL_LOHI``, ``LOAD``, ``CALL``, etc).  This is the
   biggest reason that you currently still *have to* write custom C++ code
   for your instruction selector.
 
 * There is no great way to support matching complex addressing modes yet.  In
   the future, we will extend pattern fragments to allow them to define multiple