From 3434d39bf8c32bf37381ffd3a70b2dc22aaa5f56 Mon Sep 17 00:00:00 2001
From: Ian McIntyre <ianpmcintyre@gmail.com>
Date: Sun, 21 May 2023 16:40:59 -0400
Subject: [PATCH] Add raltool config for strict enum descriptions

Similar to strict enum names, this configuration instructs the combiner
to compare enum variant descriptions, the human-readable strings
associated with items. If they're not equal, then the enums cannot be
combined.

When applied to IOMUXC peripherals, this ensures that the documentation
associated with each enum variant is correct. The next commit checks in
the updates.
---
 raltool-cfg.yaml       |  4 ++++
 raltool/src/combine.rs | 23 +++++++++++++++++++----
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/raltool-cfg.yaml b/raltool-cfg.yaml
index 07675e1f9e8a..0eeca9dc0c25 100644
--- a/raltool-cfg.yaml
+++ b/raltool-cfg.yaml
@@ -187,6 +187,10 @@ combines:
     - iomuxc
     - iomuxc_gpr
     - iomuxc_snvs
+  - StrictEnumDescs:
+    - iomuxc
+    - iomuxc_gpr
+    - iomuxc_snvs
   # IR paths that should never be combined.
   #
   # These regexes match IR paths. If there's a match, that element is *never* considered for
diff --git a/raltool/src/combine.rs b/raltool/src/combine.rs
index 7631b04e9e9b..9a44af016f0a 100644
--- a/raltool/src/combine.rs
+++ b/raltool/src/combine.rs
@@ -149,7 +149,8 @@ fn equivalent_options<E>(
 
 #[derive(Clone, Copy)]
 struct EquivalentEnums<'a> {
-    peripherals: &'a HashSet<String>,
+    names: &'a HashSet<String>,
+    descs: &'a HashSet<String>,
 }
 
 impl Equivalence<ir::Enum> for EquivalentEnums<'_> {
@@ -159,10 +160,13 @@ impl Equivalence<ir::Enum> for EquivalentEnums<'_> {
         CompareIr { elem: b, .. }: CompareIr<ir::Enum>,
         path: IrPath,
     ) -> bool {
-        let assert_name_equivalence = self.peripherals.contains(peripheral_part(path));
+        let assert_name_equivalence = self.names.contains(peripheral_part(path));
+        let assert_desc_equivalence = self.descs.contains(peripheral_part(path));
         a.bit_size == b.bit_size
             && equivalent_slices(&a.variants, &b.variants, |q, r| {
-                q.value == r.value && (!assert_name_equivalence || q.name == r.name)
+                q.value == r.value
+                    && (!assert_name_equivalence || q.name == r.name)
+                    && (!assert_desc_equivalence || q.description == r.description)
             })
     }
 }
@@ -350,7 +354,8 @@ impl<'ir> IrVersions<'ir> {
         let exclusions = &exclusions;
 
         let enums = EquivalentEnums {
-            peripherals: &config.strict_enum_names,
+            names: &config.strict_enum_names,
+            descs: &config.strict_enum_descs,
         };
         let fieldsets = EquivalentFieldSets { enums };
         let blocks = EquivalentBlocks { fieldsets };
@@ -426,6 +431,7 @@ type RefMap<'a, K, V> = HashMap<RefHash<'a, K>, V>;
 #[derive(Default)]
 pub struct Config {
     strict_enum_names: HashSet<String>,
+    strict_enum_descs: HashSet<String>,
     never_combine: HashSet<String>,
 }
 
@@ -592,6 +598,12 @@ pub enum Combine {
     /// always safe to add to this list; however, it means there may be more
     /// code generated.
     StrictEnumNames(Vec<String>),
+    /// The list of peripheral names that require strict enum description
+    /// checks.
+    ///
+    /// This is even stricter than [`StrictEnumNames`], since it asserts
+    /// equal descriptions (human-readable descriptions) for each enum variant.
+    StrictEnumDescs(Vec<String>),
     /// The list of patterns (regex string) to never combine.
     ///
     /// You should design patterns to the IR path names. Note that, unlike
@@ -612,6 +624,9 @@ where
                 Combine::StrictEnumNames(peripherals) => {
                     config.strict_enum_names.extend(peripherals);
                 }
+                Combine::StrictEnumDescs(peripherals) => {
+                    config.strict_enum_descs.extend(peripherals);
+                }
                 Combine::NeverCombine(paths) => {
                     config.never_combine.extend(paths);
                 }