From 84a0dc323d90f86e899519b31b789ed5c0a0ec9a Mon Sep 17 00:00:00 2001
From: Simon Atanasyan <simon@atanasyan.com>
Date: Fri, 23 May 2014 08:07:09 +0000
Subject: [YAML] Add an optional argument `EnumMask` to the
 `yaml::IO::bitSetCase()`.

Some bit-set fields used in ELF file headers in fact contain two parts.
The first one is a regular bit-field. The second one is an enumeraion.
For example ELF header `e_flags` for MIPS target might contain the
following values:

Bit-set values:

  EF_MIPS_NOREORDER = 0x00000001
  EF_MIPS_PIC       = 0x00000002
  EF_MIPS_CPIC      = 0x00000004
  EF_MIPS_ABI2      = 0x00000020

Enumeration:

  EF_MIPS_ARCH_32   = 0x50000000
  EF_MIPS_ARCH_64   = 0x60000000
  EF_MIPS_ARCH_32R2 = 0x70000000
  EF_MIPS_ARCH_64R2 = 0x80000000

For printing bit-sets we use the `yaml::IO::bitSetCase()`. It does not
support bit-set/enumeration combinations and prints too many flags from
an enumeration part. This patch fixes this problem. New method
`yaml::IO::maskedBitSetCase()` handle "enumeration" part of bitset
defined by provided mask.

Patch reviewed by Nick Kledzik and Sean Silva.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@209504 91177308-0d34-0410-b5e6-96231b3b80d8
---
 docs/YamlIO.rst | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

(limited to 'docs')

diff --git a/docs/YamlIO.rst b/docs/YamlIO.rst
index dfb348da2f..76dd021f82 100644
--- a/docs/YamlIO.rst
+++ b/docs/YamlIO.rst
@@ -399,6 +399,42 @@ the above schema, a same valid YAML document is:
     name:    Tom
     flags:   [ pointy, flat ]
 
+Sometimes a "flags" field might contains an enumeration part
+defined by a bit-mask.
+
+.. code-block:: c++
+
+    enum {
+      flagsFeatureA = 1,
+      flagsFeatureB = 2,
+      flagsFeatureC = 4,
+
+      flagsCPUMask = 24,
+
+      flagsCPU1 = 8,
+      flagsCPU2 = 16
+    };
+
+To support reading and writing such fields, you need to use the maskedBitSet()
+method and provide the bit values, their names and the enumeration mask.
+
+.. code-block:: c++
+
+    template <>
+    struct ScalarBitSetTraits<MyFlags> {
+      static void bitset(IO &io, MyFlags &value) {
+        io.bitSetCase(value, "featureA",  flagsFeatureA);
+        io.bitSetCase(value, "featureB",  flagsFeatureB);
+        io.bitSetCase(value, "featureC",  flagsFeatureC);
+        io.maskedBitSetCase(value, "CPU1",  flagsCPU1, flagsCPUMask);
+        io.maskedBitSetCase(value, "CPU2",  flagsCPU2, flagsCPUMask);
+      }
+    };
+
+YAML I/O (when writing) will apply the enumeration mask to the flags field,
+and compare the result and values from the bitset. As in case of a regular
+bitset, each that matches will cause the corresponding string to be added
+to the flow sequence.
 
 Custom Scalar
 -------------
-- 
cgit v1.2.3