[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

296

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 {
   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.
+  /// together. Both the incoming and outgoing carries are active high with 1
+  /// indicating the presence of a carry/borrow. Care should be taken on those
+  /// hardware architectures where some instructions use the active-low logic
+  /// for the carry/borrow flag. 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.
   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*
   /// flag, because it may be a store to memory, etc.). If the type of the
   /// boolean is not i1 then the high bits conform to getBooleanContents.
   SADDO_CARRY,
   SSUBO_CARRY,