[CodeGen] Clarify the semantics of ADDCARRY/SUBCARRY

[kazu]

Summary

This patch clarifies the semantics of ADDCARRY/SUBCARRY, specifically
stating that both the incoming and outgoing carries are active high.

[efriedma]

I don't think most people are going to be familiar with "active high"/"active low" terminology. At least, I had to look it up.

I think it makes sense to:

1. Explicitly mention the relationship with UADDO/USUBO.
2. Explicitly call out that for subtraction, the native carry flag is the inverse of what USUBO produces.

[craig.topper]

In D125130#3497763, @efriedma wrote:

I don't think most people are going to be familiar with "active high"/"active low" terminology. At least, I had to look it up.

I think it makes sense to:

1. Explicitly mention the relationship with UADDO/USUBO.
2. Explicitly call out that for subtraction, the native carry flag is the inverse of what USUBO produces.

What is meant by "native carry flag" here? X86's carry flag matches the USUBO output.

I wonder if the use of the word "carry" on subtract is misleading. Should it be "borrow" instead?

[efriedma]

What is meant by "native carry flag" here? X86's carry flag matches the USUBO output.

Sorry, missed a few words. Meant to say "Explicitly call out that for subtraction, on many targets, the native carry flag is the inverse of what USUBO produces." x86 is not one of those targets. AArch64 is.

[kazu]

Included a comparison to [US]{ADD,SUB}O.

Split the description to several paragraphs, separating the definition
proper and supplemental information.

[kazu]

In D125130#3497763, @efriedma wrote:

I don't think most people are going to be familiar with "active high"/"active low" terminology. At least, I had to look it up.

OK. I've replaced them with "if and only if" phrases.

I think it makes sense to:

1. Explicitly mention the relationship with UADDO/USUBO.
2. Explicitly call out that for subtraction, the native carry flag is the inverse of what USUBO produces.

I am not sure if the latest revision addresses your comment about UADD/USUBO. If not, I'd like to drop the last paragraph about [US]{ADD,SUB}O and check in the rest. I think it's important to check in the precise definition first. We can always add supplemental information later. Thanks!

[efriedma]

The reason I mention UADDO/USUBO is because that's what we use to represent the initial operation, usually. If you think it's not important, we can leave that bit out.

[Kmeakin]

Typo in spelling of "semantics". Otherwise seems fine to me.

[craig.topper]

llvm/include/llvm/CodeGen/ISDOpcodes.h

293

Should this be "add/sub" to match the order of "carry/borrow" used?

[kazu]

Fixed the typo of semantics.

Replaced sub/add with add/sub.

llvm/include/llvm/CodeGen/ISDOpcodes.h

enum NodeType {
   /// carry flag.  These nodes both read and write a carry flag to allow them
   /// to them to be chained together for add and sub of arbitrarily large
   /// values.
   ADDE,
   SUBE,
 
   /// Carry-using nodes for multiple precision addition and subtraction.
   /// These nodes take three operands: The first two are the normal lhs and
-  /// rhs to the add or sub, and the third is a boolean indicating if there
-  /// is an incoming carry. These nodes produce two results: the normal
-  /// result of the add or sub, and the output carry so they can be chained
-  /// together. The use of this opcode is preferable to adde/sube if the
-  /// target supports it, as the carry is a regular value rather than a
-  /// glue, which allows further optimisation.
+  /// rhs to the add or sub, and the third is a boolean value that is 1 if and
+  /// only if there is an incoming carry/borrow. These nodes produce two
+  /// results: the normal result of the add or sub, and a boolean value that is
+  /// 1 if and only if there is an outgoing carry/borrow.
+  ///
+  /// Care must be taken if these opcodes are lowered to hardware instructions
+  /// that use the inverse logic -- 0 if and only if there is an
+  /// incoming/outgoing carry/borrow.  In such cases, you must preserve the
+  /// semantics of these opcodes by inverting the incoming carry/borrow, feeding
+  /// it to the add/sub hardware instruction, and then inverting the outgoing
+  /// carry/borrow.
+  ///
+  /// The use of these opcodes is preferable to adde/sube if the target supports
+  /// it, as the carry is a regular value rather than a glue, which allows
+  /// further optimisation.
+  ///
+  /// These opcodes are different from [US]{ADD,SUB}O in that ADDCARRY/SUBCARRY
+  /// consume and produce a carry/borrow, whereas [US]{ADD,SUB}O produce an
+  /// overflow.
   ADDCARRY,
   SUBCARRY,
 
   /// Carry-using overflow-aware nodes for multiple precision addition and
   /// subtraction. These nodes take three operands: The first two are normal lhs
   /// and rhs to the add or sub, and the third is a boolean indicating if there
   /// is an incoming carry. They produce two results: the normal result of the
   /// add or sub, and a boolean that indicates if an overflow occurred (*not*