From 00c7050fc906fa248949f62ac2b4830802c16fce Mon Sep 17 00:00:00 2001
From: Andreas Neiser <neiser@kph.uni-mainz.de>
Date: Sat, 29 Jun 2013 16:11:16 +0200
Subject: [PATCH] Improving the schema (stricter element handling), introducing
 "enum" format type

---
 xml-db/database/TDC.xml                 |  28 ++--
 xml-db/database/TrbNetEntity.xsd        | 167 +++++++++++++++---------
 xml-db/database/jtag_registers_SPEC.xml |   1 +
 xml-db/database/testing.xml             |   1 +
 4 files changed, 123 insertions(+), 74 deletions(-)

diff --git a/xml-db/database/TDC.xml b/xml-db/database/TDC.xml
index 2778e52..50d1cf7 100644
--- a/xml-db/database/TDC.xml
+++ b/xml-db/database/TDC.xml
@@ -4,25 +4,27 @@
         name="TDC"
         address="c000"
         >
+  <description>An FPGA-based tapped-delay line TDC</description>
   <!--===========================================-->
-  <!-- Common TDC control registers             -->
+  <!-- Common TDC Status registers             -->
   <!--===========================================-->
-  <group name="Control"
-         address="1000"  size="37"  function="config"  mode="rw"  continuous="true">
-    <register name="WaitBeforeStart"
-              address="0007" mode="rw" function ="config" >
-      <description>Wait time between write sequence and start signal.</description>
-      <field name="WaitBeforeStart"
-             start="0"   size="20"  mode="rw"  type="config"  format="integer"  defaultValue="0" >
-        <description>The number of MAPS clock cycles to wait after last write before sending the start signal. </description>
+  <group name="Status" function="config" address="0100"  mode="rw"  continuous="true">
+    <register name="Basic"
+              address="0000" mode="rw">
+      <description>Basic controls</description>
+      <field name="FSMReadout"
+             start="0"   size="20"  mode="rw"  type="config"  format="enum"  defaultValue="0" >
+        <description>Debug word of the TDC readout FSM</description>       
+        <enumItem value="a">bla</enumItem>
       </field>
+      
     </register>
     <register name="TriggerInitSeq"
-              address="000c" mode="w" function ="trigger" >
-      <description>Trigger the init sequence.</description>
+              address="0001" mode="w" function ="trigger" repeat="2">
+      <description>Trig</description>
       <field name="TriggerInitSeq"
-             start="0"   size="5"  mode="w"  type="trigger"  format="bitmask"  defaultValue="0" >
-        <description>A bitmask to trigger the init sequence on individual JTAG chains. </description>
+             start="0"   size="32"  mode="w"  type="trigger"  format="bitmask"  defaultValue="0" >
+        <description>Empty signals (hits?) of channels</description>
       </field>
     </register>
     <register name="TriggerReset"
diff --git a/xml-db/database/TrbNetEntity.xsd b/xml-db/database/TrbNetEntity.xsd
index c2cc6f1..e5c36bb 100644
--- a/xml-db/database/TrbNetEntity.xsd
+++ b/xml-db/database/TrbNetEntity.xsd
@@ -8,19 +8,19 @@
     <xs:restriction base="xs:string">
       <xs:pattern value="[0-9a-zA-Z_]+"/>
     </xs:restriction>
-  </xs:simpleType> 
+  </xs:simpleType>
 
   <xs:simpleType name="addresstype">
     <xs:restriction base="xs:string">
       <xs:pattern value="[0-9a-fA-F]{4}"/>
     </xs:restriction>
-  </xs:simpleType> 
+  </xs:simpleType>
 
   <xs:simpleType name="valuetype">
     <xs:restriction base="xs:string">
       <xs:pattern value="[0-9a-fA-F]+"/>
     </xs:restriction>
-  </xs:simpleType> 
+  </xs:simpleType>
 
   <xs:simpleType name="modetype">
     <xs:restriction base="xs:string">
@@ -29,18 +29,18 @@
            no-more-data from this registers transports some vital
            information -->
     </xs:restriction>
-  </xs:simpleType> 
+  </xs:simpleType>
 
   <xs:simpleType name="functiontype">
     <!-- config: setup some behaviour
          trigger: register which starts some kind of operation of the hardware
          status: slowly changing information
          statistics: quickly changing information
-  
+         ***
          Note: The difference between "status" and "statistics" is not sharp,
          they both give some information about the system. Usually, statistics
          is updated every event (e.g. number of read-out triggers received),
-         whereas status contains more "constant" stuff (e.g. temperature)   
+         whereas status contains more "constant" stuff (e.g. temperature)
     -->
     <xs:restriction base="xs:string">
       <xs:enumeration value="config"/>
@@ -48,14 +48,14 @@
       <xs:enumeration value="status"/>
       <xs:enumeration value="statistics"/>
     </xs:restriction>
-  </xs:simpleType> 
+  </xs:simpleType>
 
   <xs:simpleType name="bittype">
     <xs:restriction base="xs:integer">
       <xs:minInclusive value="0"/>
       <xs:maxInclusive value="31"/>
     </xs:restriction>
-  </xs:simpleType> 
+  </xs:simpleType>
 
   <xs:simpleType name="formattype">
     <xs:restriction base="xs:string">
@@ -68,15 +68,16 @@
       <xs:enumeration value="boolean"/>
       <xs:enumeration value="time"/>
       <xs:enumeration value="string"/>
+      <xs:enumeration value="enum"/>
     </xs:restriction>
-  </xs:simpleType> 
+  </xs:simpleType>
+
 
   <!--==============================
       Attribute Definition
       ==============================-->
   <xs:attribute name="name"         type="nametype" />
   <xs:attribute name="address"      type="addresstype" />
-  <xs:attribute name="offset"       type="addresstype" />
   <xs:attribute name="mode"         type="modetype"  />
   <xs:attribute name="type"         type="functiontype" />
   <xs:attribute name="function"     type="functiontype" />
@@ -95,32 +96,48 @@
       ==============================-->
   <xs:element name="description" type="xs:string" />
 
+
   <!--==============================
       Complex Elements
       ==============================-->
   <xs:element name="TrbNetEntity">
     <xs:complexType>
-      <xs:choice maxOccurs="unbounded">
-        <xs:element   ref="description" minOccurs="1" maxOccurs="1" />
-        <xs:element   ref="group"       maxOccurs="unbounded" />
-        <xs:element   ref="register"    maxOccurs="unbounded" />
-        <xs:element   ref="memory"      maxOccurs="unbounded" />
-        <xs:element   ref="fifo"        maxOccurs="unbounded" />
-      </xs:choice>
-      <xs:attribute ref="name" />
+      <xs:sequence>
+        <!-- we expect description to give a summary of this whole
+             entity, thus this field is required at the beginning -->
+        <xs:choice>
+          <xs:element   ref="description"/>
+        </xs:choice>
+        <!-- but a data without any fields does not make sense for this
+             database, so the default minOccurs=1 is used -->
+        <xs:choice maxOccurs="unbounded">
+          <xs:element   ref="group"       maxOccurs="unbounded" />
+          <xs:element   ref="register"    maxOccurs="unbounded" />
+          <xs:element   ref="memory"      maxOccurs="unbounded" />
+          <xs:element   ref="fifo"        maxOccurs="unbounded" />
+        </xs:choice>
+      </xs:sequence>
+      <xs:attribute ref="name" use="required" />
       <xs:attribute ref="address" />
     </xs:complexType>
   </xs:element>
 
   <xs:element name="group">
     <xs:complexType>
-      <xs:choice maxOccurs="unbounded">
-        <xs:element   ref="group"       maxOccurs="unbounded" />
-        <xs:element   ref="description" minOccurs="1" maxOccurs="1" />
-        <xs:element   ref="register"    maxOccurs="unbounded" />
-        <xs:element   ref="memory"      maxOccurs="unbounded" />
-        <xs:element   ref="fifo"        maxOccurs="unbounded" />
-      </xs:choice>
+      <xs:sequence>
+        <!-- a group does not necessarily need a description -->
+        <xs:choice minOccurs="0">
+          <xs:element   ref="description"/>
+        </xs:choice>
+        <!-- but a data without any fields does not make sense for this
+             database, so the default minOccurs=1 is used -->
+        <xs:choice maxOccurs="unbounded">
+          <xs:element   ref="group"       maxOccurs="unbounded" />
+          <xs:element   ref="register"    maxOccurs="unbounded" />
+          <xs:element   ref="memory"      maxOccurs="unbounded" />
+          <xs:element   ref="fifo"        maxOccurs="unbounded" />
+        </xs:choice>
+      </xs:sequence>
       <xs:attribute ref="name" use="required" />
       <xs:attribute ref="address" />
       <xs:attribute ref="size" />
@@ -130,15 +147,33 @@
       <xs:attribute ref="format" />
       <xs:attribute ref="repeat" />
     </xs:complexType>
-  </xs:element> 
+  </xs:element>
 
+  <xs:element name="enumItem">
+    <xs:complexType>
+      <xs:simpleContent>
+        <xs:extension base="xs:string">
+          <xs:attribute name="value" type="valuetype" />
+        </xs:extension>
+      </xs:simpleContent>
+    </xs:complexType>
+  </xs:element>
 
   <xs:element name="field">
     <xs:complexType>
-      <xs:all>
-        <xs:element   ref="description" minOccurs="1" maxOccurs="1" />
-      </xs:all>
-      <xs:attribute ref="name" />
+      <xs:sequence>
+        <xs:choice>
+          <xs:element   ref="description"/>
+        </xs:choice>
+        <xs:choice minOccurs="0" maxOccurs="unbounded">
+          <!-- enum items are only meaningful for format="enum"
+               fields, however we don't complain if there are some for
+               other formats... -->
+          <xs:element   ref="enumItem" />
+        </xs:choice>
+      </xs:sequence>
+
+      <xs:attribute ref="name" use="required" />
       <xs:attribute ref="start" />
       <xs:attribute ref="size" />
       <xs:attribute ref="type" />
@@ -150,50 +185,60 @@
            an error is indicated by this field -->
       <xs:attribute ref="errorflag" />
     </xs:complexType>
-  </xs:element> 
+  </xs:element>
 
 
-  <xs:element name="register">
-    <xs:complexType>
+  <xs:complexType name="basicTrbData">
+    <xs:sequence>
+      <!-- in contrast to the "field" elements, a description is not
+           required here -->
+      <xs:choice minOccurs="0">
+        <xs:element   ref="description"/>
+      </xs:choice>
+      <!-- but a data without any fields does not make sense for this
+           database, so the default minOccurs=1 is used -->
       <xs:choice maxOccurs="unbounded">
         <xs:element   ref="field" />
-        <xs:element   ref="description" minOccurs="1" maxOccurs="1" />
       </xs:choice>
-      <xs:attribute ref="name" />
-      <xs:attribute ref="address" />
-      <xs:attribute ref="mode" />
-      <xs:attribute ref="function" />
-      <xs:attribute ref="repeat" />
+    </xs:sequence>
+    <xs:attribute ref="name" use="required" />
+    <xs:attribute ref="address" use="required" />
+    <xs:attribute ref="mode" />
+    <xs:attribute ref="function" />
+  </xs:complexType>
+
+
+  <xs:element name="register">
+    <xs:complexType>
+      <xs:complexContent>
+        <xs:extension base="basicTrbData">
+          <xs:attribute ref="repeat" />
+        </xs:extension>
+      </xs:complexContent>
     </xs:complexType>
-  </xs:element> 
+  </xs:element>
 
   <xs:element name="memory">
     <xs:complexType>
-      <xs:choice maxOccurs="unbounded">
-        <xs:element   ref="field" />
-        <xs:element   ref="description" minOccurs="1" maxOccurs="1" />
-      </xs:choice>
-      <xs:attribute ref="name" />
-      <xs:attribute ref="address" />
-      <xs:attribute ref="size" />
-      <xs:attribute ref="mode" />
-      <xs:attribute ref="function" />
+      <xs:complexContent>
+        <xs:extension base="basicTrbData">
+          <xs:attribute ref="size" />
+        </xs:extension>
+      </xs:complexContent>
     </xs:complexType>
-  </xs:element> 
+  </xs:element>
 
   <xs:element name="fifo">
     <xs:complexType>
-      <xs:choice maxOccurs="unbounded">
-        <xs:element   ref="field" />
-        <xs:element   ref="description" minOccurs="1" maxOccurs="1" />
-      </xs:choice>
-      <xs:attribute ref="name" />
-      <xs:attribute ref="address" />
-      <xs:attribute ref="mode" />
-      <xs:attribute ref="function" />
+      <xs:complexContent>
+        <xs:extension base="basicTrbData">
+          <!-- a fifo is currently not different at all from
+               basicTrbData, but we keep this complicated definition
+               for future extensions -->
+        </xs:extension>
+      </xs:complexContent>
     </xs:complexType>
-  </xs:element> 
-
+  </xs:element>
 
-</xs:schema> 
 
+</xs:schema>
diff --git a/xml-db/database/jtag_registers_SPEC.xml b/xml-db/database/jtag_registers_SPEC.xml
index 9ea9710..027fa53 100644
--- a/xml-db/database/jtag_registers_SPEC.xml
+++ b/xml-db/database/jtag_registers_SPEC.xml
@@ -4,6 +4,7 @@
         name="JtagController"
         address="a000"
         >
+  <description>A JTAG controller for Pixel Sensors?</description>
   <!--===========================================-->
   <!-- Common JTAG control registers             -->
   <!--===========================================-->
diff --git a/xml-db/database/testing.xml b/xml-db/database/testing.xml
index b7bec3f..03fda0d 100644
--- a/xml-db/database/testing.xml
+++ b/xml-db/database/testing.xml
@@ -4,6 +4,7 @@
         name="JtagController"
         address="1000"
         >
+  <description>Just some testing</description>
   <group
       name="JtagCommonControl"
       address="0000"
-- 
2.43.0