Index: llvm/test/tools/obj2yaml/relocation-addend.yaml
===================================================================
--- /dev/null
+++ llvm/test/tools/obj2yaml/relocation-addend.yaml
@@ -0,0 +1,108 @@
+## Test how obj2yaml emits relocation addend descriptions.
+## We document that relocation addends are dumped as signed int64 decimal values.
+
+## Case 1: Check a 64-bit object.
+
+## Check how obj2yaml dumps an addend with an arbitrary positive value.
+## We use 1 as it is the first possible positive value.
+# RUN: yaml2obj --docnum=1 %s -o %t1 -D ADDEND=1
+# RUN: obj2yaml %t1 | FileCheck %s --check-prefix=ELF64 --match-full-lines -DADDEND=1
+
+# ELF64:      Relocations:
+# ELF64-NEXT:  - Offset: 0x0000000000000000
+# ELF64-NEXT:    Symbol: foo
+# ELF64-NEXT:    Type:   R_X86_64_PC32
+# ELF64-NEXT:    Addend: [[ADDEND]]
+
+## Check how obj2yaml dumps an addend with an arbitrary negative value.
+## We use -1 as it is the first possible negative value.
+# RUN: yaml2obj --docnum=1 %s -o %t2 -D ADDEND=-1
+# RUN: obj2yaml %t2 | FileCheck %s --check-prefix=ELF64 --match-full-lines -DADDEND=-1
+
+## Check how obj2yaml dumps an addend with the value INT64_MAX.
+# RUN: yaml2obj --docnum=1 %s -o %t3 -D ADDEND=9223372036854775807
+# RUN: obj2yaml %t3 | FileCheck %s --check-prefix=ELF64 --match-full-lines -DADDEND=9223372036854775807
+
+## Check how obj2yaml dumps an addend with the value INT64_MIN.
+# RUN: yaml2obj --docnum=1 %s -o %t4 -D ADDEND=-9223372036854775808
+# RUN: obj2yaml %t4 | FileCheck %s --check-prefix=ELF64 --match-full-lines -DADDEND=-9223372036854775808
+
+--- !ELF
+FileHeader:
+  Class:   ELFCLASS64
+  Data:    ELFDATA2LSB
+  Type:    ET_REL
+  Machine: EM_X86_64
+Sections:
+  - Name: .text
+    Type: SHT_PROGBITS
+  - Name: .rela.text
+    Type: SHT_RELA
+    Info: .text
+    Link: .symtab
+    Relocations:
+      - Type:   R_X86_64_PC32
+        Offset: 0x0
+        Symbol: foo
+        Addend: [[ADDEND]]
+Symbols:
+  - Name: foo
+
+## Check that obj2yaml omits zero addends.
+# RUN: yaml2obj --docnum=1 %s -o %t5 -D ADDEND=0
+# RUN: obj2yaml %t5 | FileCheck %s --implicit-check-not="Addend:"
+# RUN: yaml2obj --docnum=1 %s -o %t6 -D ADDEND=0x0
+# RUN: obj2yaml %t6 | FileCheck %s --implicit-check-not="Addend:"
+
+## Case 2: Check a 32-bit object.
+
+## Check how obj2yaml dumps an addend with an arbitrary positive value.
+## We use 1 as it is the first possible positive value.
+# RUN: yaml2obj --docnum=2 %s -o %t7 -D ADDEND=1
+# RUN: obj2yaml %t7 | FileCheck %s --check-prefix=ELF32 --match-full-lines -DADDEND=1
+
+# ELF32:      Relocations:
+# ELF32-NEXT:  - Offset: 0x0000000000000000
+# ELF32-NEXT:    Symbol: foo
+# ELF32-NEXT:    Type:   R_386_PC32
+# ELF32-NEXT:    Addend: [[ADDEND]]
+
+## Check how obj2yaml dumps an addend with an arbitrary negative value.
+## We use -1 as it is the first possible negative value.
+# RUN: yaml2obj --docnum=2 %s -o %t8 -D ADDEND=-1
+# RUN: obj2yaml %t8 | FileCheck %s --check-prefix=ELF32 --match-full-lines -DADDEND=-1
+
+## Check how obj2yaml dumps an addend with the value INT32_MAX.
+# RUN: yaml2obj --docnum=2 %s -o %t9 -D ADDEND=2147483647
+# RUN: obj2yaml %t9 | FileCheck %s --check-prefix=ELF32 --match-full-lines -DADDEND=2147483647
+
+## Check how obj2yaml dumps an addend with the value INT32_MIN.
+# RUN: yaml2obj --docnum=2 %s -o %t10 -D ADDEND=-2147483648
+# RUN: obj2yaml %t10 | FileCheck %s --check-prefix=ELF32 --match-full-lines -DADDEND=-2147483648
+
+## Check that obj2yaml omits zero addends.
+# RUN: yaml2obj --docnum=2 %s -o %t11 -D ADDEND=0
+# RUN: obj2yaml %t11 | FileCheck %s --implicit-check-not="Addend:"
+# RUN: yaml2obj --docnum=2 %s -o %t12 -D ADDEND=0x0
+# RUN: obj2yaml %t12 | FileCheck %s --implicit-check-not="Addend:"
+
+--- !ELF
+FileHeader:
+  Class:   ELFCLASS32
+  Data:    ELFDATA2LSB
+  Type:    ET_REL
+  Machine: EM_386
+Sections:
+  - Name: .text
+    Type: SHT_PROGBITS
+  - Name: .rela.text
+    Type: SHT_RELA
+    Info: .text
+    Link: .symtab
+    Relocations:
+      - Type:   R_386_PC32
+        Offset: 0x0
+        Symbol: foo
+        Addend: [[ADDEND]]
+Symbols:
+  - Name: foo
Index: llvm/test/tools/yaml2obj/ELF/relocation-addend.yaml
===================================================================
--- /dev/null
+++ llvm/test/tools/yaml2obj/ELF/relocation-addend.yaml
@@ -0,0 +1,117 @@
+## Here we document how yaml2obj handles handles relocation addend descriptions.
+
+## Case 1: Check a 64-bit object.
+
+## Case 1.1: Document we accept an addend with the
+## value INT64_MAX = 2^63-1 = 0x7FFFFFFFFFFFFFFF = 9223372036854775807.
+
+# RUN: yaml2obj %s -o %t1 -D ADDEND=9223372036854775807
+# RUN: llvm-readobj -r %t1 | FileCheck %s --check-prefix=MAX64
+# RUN: yaml2obj %s -o %t2 -D ADDEND=0x7FFFFFFFFFFFFFFF
+# RUN: llvm-readobj -r %t2 | FileCheck %s --check-prefix=MAX64
+
+# MAX64: 0x0 R_X86_64_PC32 foo 0x7FFFFFFFFFFFFFFF
+
+## Case 1.2: Check we report an error when an addend is greater than INT64_MAX and
+## it is in decimal form. We use (INT64_MAX + 1).
+# RUN: not yaml2obj %s -o %t3 -D ADDEND=9223372036854775808 2>&1 | FileCheck %s --check-prefix=OVERFLOW64
+
+# OVERFLOW64: error: invalid number
+
+## Case 1.3: Document we accept an addend with the
+## value INT64_MIN = -2^63 = 0x8000000000000000 = -9223372036854775808.
+
+# RUN: yaml2obj %s -o %t3 -D ADDEND=-9223372036854775808
+# RUN: llvm-readobj -r %t3 | FileCheck %s --check-prefix=MIN64
+
+# MIN64: 0x0 R_X86_64_PC32 foo 0x8000000000000000
+
+## FIXME: We should support the following case instead.
+# RUN: not yaml2obj %s -o /dev/null -D ADDEND=0x8000000000000000 2>&1 | FileCheck %s --check-prefix=OVERFLOW64
+
+## Case 1.4: Check we report an error when an addend is less than INT64_MIN and
+## it is in decimal form. We use (INT64_MIN - 1).
+# RUN: not yaml2obj %s -o /dev/null -D ADDEND=-9223372036854775809 2>&1 | FileCheck %s --check-prefix=OVERFLOW64
+
+--- !ELF
+FileHeader:
+  Class:   ELFCLASS64
+  Data:    ELFDATA2LSB
+  Type:    ET_REL
+  Machine: EM_X86_64
+Sections:
+  - Name: .text
+    Type: SHT_PROGBITS
+  - Name: .rela.text
+    Type: SHT_RELA
+    Info: .text
+    Link: .symtab
+    Relocations:
+      - Type:   R_X86_64_PC32
+        Offset: 0x0
+        Symbol: foo
+        Addend: [[ADDEND]]
+Symbols:
+  - Name: foo
+
+## Case 2: Check a 32-bit object.
+
+## Case 2.1: Document we accept an addend with the
+## value INT32_MAX = 2^31-1 = 0x7FFFFFFF = 2,147,483,647.
+
+# RUN: yaml2obj --docnum=2 %s -o %t4 -D ADDEND=2147483647
+# RUN: llvm-readobj -r %t4 | FileCheck %s --check-prefix=MAX32
+# RUN: yaml2obj --docnum=2 %s -o %t5 -D ADDEND=0x7FFFFFFF
+# RUN: llvm-readobj -r %t5 | FileCheck %s --check-prefix=MAX32
+
+# MAX32: 0x0 R_386_PC32 foo 0x7FFFFFFF{{$}}
+
+## Case 2.2: Check we report an error when an addend is greater than INT32_MAX and
+## it is specified in decimal form. We use (INT32_MAX + 1).
+
+## FIXME: The following case should fail, see OVERFLOW64.
+# RUN: yaml2obj --docnum=2 %s -o %t6 -D ADDEND=2147483648
+# RUN: llvm-readobj -r %t6 | FileCheck %s --check-prefix=OVERFLOW32-1
+
+# OVERFLOW32-1: 0x0 R_386_PC32 foo 0x80000000{{$}}
+
+## Case 2.3: Document we accept an addend with the
+## value INT32_MIN = -2^31 = 0x80000000 = -2,147,483,648.
+
+# RUN: yaml2obj --docnum=2 %s -o %t7 -D ADDEND=-2147483648
+# RUN: llvm-readobj -r %t7 | FileCheck %s --check-prefix=MIN32
+
+# RUN: yaml2obj --docnum=2 %s -o %t8 -D ADDEND=0x80000000
+# RUN: llvm-readobj -r %t8 | FileCheck %s --check-prefix=MIN32
+
+# MIN32: 0x0 R_386_PC32 foo 0x80000000{{$}}
+
+## Case 2.4: Check we report an error when an addend is less than INT32_MIN and
+## it is in decimal form. We use (INT32_MIN - 1).
+
+## FIXME: The following case should fail, see OVERFLOW64.
+# RUN: yaml2obj --docnum=2 %s -o %t9 -D ADDEND=-2147483649
+# RUN: llvm-readobj -r %t9 | FileCheck %s --check-prefix=OVERFLOW32-2
+
+# OVERFLOW32-2: 0x0 R_386_PC32 foo 0x7FFFFFFF{{$}}
+
+--- !ELF
+FileHeader:
+  Class:   ELFCLASS32
+  Data:    ELFDATA2LSB
+  Type:    ET_REL
+  Machine: EM_386
+Sections:
+  - Name: .text
+    Type: SHT_PROGBITS
+  - Name: .rela.text
+    Type: SHT_RELA
+    Info: .text
+    Link: .symtab
+    Relocations:
+      - Type:   R_386_PC32
+        Offset: 0x0
+        Symbol: foo
+        Addend: [[ADDEND]]
+Symbols:
+  - Name: foo