Forcing unique register and field names, and registers must have a description

diff --git a/xml-db/database/TDC.xml b/xml-db/database/TDC.xml
index cf6af062bfea96d6840d4684c5dcefa40fb0aedb..868dded9776968f2696731d47036b476f016d3c5 100644 (file)
--- a/xml-db/database/TDC.xml
+++ b/xml-db/database/TDC.xml
@@ -5,12 +5,31 @@
               address="c000"
               >
   <description>An FPGA-based tapped-delay line time-to-digital converter (TDC)</description>
+
+  <!--===========================================-->
+  <!-- TDC Channels                              -->
+  <!--===========================================-->
+  <register name="Channel" address="0000" mode="r" repeat="65">
+    <description>Channel-specific information</description>
+    <field name="HitCounter" start="0" size="24" format="unsigned" purpose="statistics">
+      <description>Number of detected hits in channel</description>
+    </field>
+    <field name="InputState" start="31" size="1" format="enum" purpose="status">
+      <description>State of LVDS input buffer</description>
+      <enumItem value="0">Low</enumItem>
+      <enumItem value="1">High</enumItem>
+    </field>
+  </register>
+
+
+
   <!--===========================================-->
   <!-- TDC Status registers (mostly statistics)  -->
   <!--===========================================-->
 
   <group name="Status" purpose="statistics" address="0100"  mode="r" continuous="true">
-    <register name="Basic" address="0000" purpose="status">
+    <register name="BasicStatus" address="0000" purpose="status">
+      <description>Basic config and status information for all channels</description>
       <field name="ReadoutFSM" start="0"   size="4" format="enum" purpose="status">
         <description>Debug word of the TDC readout FSM</description>
         <enumItem value="1">IDLE</enumItem>
@@ -43,135 +62,122 @@
     </register>
 
     <memory name="EmptyChannels" address="0001" size="2" mode="w" purpose="trigger">
-      <field name="Mask" start="0" size="64" format="bitmask">
-        <description>Empty the signals/hits of the specific channel.
-        LSB is channel 1.</description>
-      </field>
+      <description>Empty the signals/hits of the specific channel. LSB
+      is channel 1.</description>
+      <field name="Mask" start="0" size="64" format="bitmask" />
     </memory>
 
-    <register name="TriggerWindow" address="0003" purpose="status">
-      <field name="Before" start="0" size="11" format="time" unit="ns" scale="5">
+    <register name="TriggerWindowStatus" address="0003" purpose="status">
+      <description>Status of the TriggerWindow feature</description>
+      <field name="TriggerWindowBeforeValue" start="0" size="11" format="time" unit="ns" scale="5">
         <description>Trigger window width BEFORE the trigger with
         granularity of 5 ns</description>
       </field>
-      <field name="After" start="16" size="11" format="time" unit="ns" scale="5">
+      <field name="TriggerWindowAfterValue" start="16" size="11" format="time" unit="ns" scale="5">
         <description>Trigger window width AFTER the trigger with
         granularity of 5 ns</description>
       </field>
-      <field name="Enable" start="31" format="boolean">
+      <field name="TriggerWindowEnabled" start="31" format="boolean">
         <description>Trigger window enabled?</description>
       </field>
     </register>
 
-    <register name="Trigger" address="0004">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of valid triggers received</description>
-      </field>
+    <register name="TriggerCounter" address="0004">
+      <description>Number of valid triggers received</description>
+      <field name="TriggerCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="TimingTrigger" address="0005">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of valid timing triggers
-        received</description>
-      </field>
+    <register name="TimingTriggerCounter" address="0005">
+      <description>Number of valid timing triggers
+      received</description>
+      <field name="TimingTriggerCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="NoTimingTrigger" address="0006">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of valid triggers received which are not
-        timing triggers</description>
-      </field>
+    <register name="NoTimingTriggerCounter" address="0006">
+      <description>Number of valid triggers received which are not
+      timing triggers</description>
+      <field name="NoTimingTriggerCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="InvalidTrigger" address="0007">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of invalid triggers received</description>
-      </field>
+    <register name="InvalidTriggerCounter" address="0007">
+      <description>Number of invalid triggers received</description>
+      <field name="InvalidTriggerCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="MultiTimingTrigger" address="0008">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of multi timing triggers received
-        (triggers received before trigger is released)</description>
-      </field>
+    <register name="MultiTimingTriggerCounter" address="0008">
+      <description>Number of multi timing triggers received (triggers
+      received before trigger is released)</description>
+      <field name="MultiTimingTriggerCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="SpuriousTrigger" address="0009">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of spurious triggers received (in case of
-        timing trigger is validated although it was a
-        timing-trigger-less trigger)</description>
-      </field>
+    <register name="SpuriousTriggerCounter" address="0009">
+      <description>Number of spurious triggers received (in case of
+      timing trigger is validated although it was a
+      timing-trigger-less trigger)</description>
+      <field name="SpuriousTriggerCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="WrongReadouts" address="000a">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of wrong readouts due to spurious triggers</description>
-      </field>
+    <register name="WrongReadoutsCounter" address="000a">
+      <description>Number of wrong readouts due to spurious
+      triggers</description>
+      <field name="WrongReadoutsCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="Spikes" address="000b">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of spikes (pulses narrower than 40 ns)
-        detected at the timing trigger input</description>
-      </field>
+    <register name="SpikesCounter" address="000b">
+      <description>Number of spikes (pulses narrower than 40 ns)
+      detected at the timing trigger input</description>
+      <field name="SpikesCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="Idle" address="000c">
-      <field name="Time" start="0" size="24" format="time" unit="ns" scale="10">
-        <description>Total time length, that the readout FSM waited in
-        the idle state (with granularity of 10 ns)</description>
-      </field>
+    <register name="IdleTime" address="000c">
+      <description>Total time length, that the readout FSM waited in
+      the idle state (with granularity of 10 ns)</description>
+      <field name="IdleTime" start="0" size="24" format="time" unit="ns" scale="10" />
     </register>
-    
-    <register name="Wait" address="000d">
-      <field name="Time" start="0" size="24" format="time" unit="ns" scale="10">
-        <description>Total time length, that the readout FSM waited in
-        the wait states (with granularity of 10 ns)</description>
-      </field>
+
+    <register name="WaitTime" address="000d">
+      <description>Total time length, that the readout FSM waited in
+      the wait states (with granularity of 10 ns)</description>
+      <field name="WaitTime" start="0" size="24" format="time" unit="ns" scale="10" />
     </register>
 
-    <register name="TotalEmptyChannels" address="000e">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Total number of empty channels since the last reset
-        signal</description>
-      </field>
+    <register name="TotalEmptyChannelsCounter" address="000e">
+      <description>Total number of empty channels since the last reset
+      signal</description>
+      <field name="TotalEmptyChannelsCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="Release" address="000f">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of release signals sent</description>
-      </field>
+    <register name="ReleaseCounter" address="000f">
+      <description>Number of release signals sent</description>
+      <field name="ReleaseCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="Readout" address="0010">
-      <field name="Time" start="0" size="24" format="time" unit="ns" scale="10">
-        <description>Total time length of the readout process 
-        (with granularity of 10 ns)</description>
-      </field>
+    <register name="ReadoutTime" address="0010">
+      <description>Total time length of the readout process (with
+      granularity of 10 ns)</description>
+      <field name="ReadoutTime" start="0" size="24" format="time" unit="ns" scale="10" />
     </register>
 
-    <register name="Timeout" address="0011">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of timeouts detected (too long delay after
-        the timing trigger)</description>
-      </field>
+    <register name="TimeoutCounter" address="0011">
+      <description>Number of timeouts detected (too long delay after
+      the timing trigger)</description>
+      <field name="TimeoutCounter" start="0" size="24" format="unsigned" />
     </register>
 
-    <register name="Finished" address="0012">
-      <field name="Counter" start="0" size="24" format="unsigned">
-        <description>Number of sent finished signals</description>
-      </field>
+    <register name="FinishedCounter" address="0012">
+      <description>Number of sent finished signals</description>
+      <field name="FinishedCounter" start="0" size="24" format="unsigned" />
     </register>
-    
+
   </group>
-  
+
   <!--===========================================-->
   <!-- TDC control registers                     -->
   <!--===========================================-->
   <group name="Control"
          address="0800" purpose="config"  mode="rw"  continuous="true">
-    <register name="Basic" address="0000">
+    <register name="BasicControl" address="0000">
+      <description>Basic control for all channels</description>
       <field name="DebugOutput" start="0" size="4" format="enum">
         <description>Enables different signals to the HPLA* output for
         debugging with logic analyser</description>
@@ -191,33 +197,33 @@
       </field>
     </register>
 
-    <register name="TriggerWindow" address="0001">
-      <field name="Before" start="0" size="11" format="time" unit="ns" scale="5">
+    <register name="TriggerWindowConfig" address="0001">
+      <description>Configuration of the TriggerWindow feature</description>
+      <field name="TriggerWindowBefore" start="0" size="11" format="time" unit="ns" scale="5">
         <description>Trigger window width BEFORE the trigger with
         granularity of 5 ns</description>
       </field>
-      <field name="After" start="16" size="11" format="time" unit="ns" scale="5">
+      <field name="TriggerWindowAfter" start="16" size="11" format="time" unit="ns" scale="5">
         <description>Trigger window width AFTER the trigger with
         granularity of 5 ns. ATTENTION: Minimum value is x"00f"!</description>
       </field>
-      <field name="Enable" start="31" format="boolean">
+      <field name="TriggerWindowEnable" start="31" format="boolean">
         <description>Trigger window enable</description>
       </field>
     </register>
 
-    <memory name="Channel" address="0002" size="2">
-      <field name="Enable" start="0" size="64" format="bitmask">
-        <description>Enable signals/hits of the specific channel.
-        LSB is channel 1.</description>
-      </field>
+    <memory name="ChannelEnable" address="0002" size="2">
+      <description>Enable signals/hits of the specific channel. LSB is
+      channel 1.</description>
+      <field name="Enable" start="0" size="64" format="bitmask" />
     </memory>
 
     <register name="DataTransferLimit" address="0004">
+      <description>Configuration of the data transfer limit feature</description>
       <field name="MaxWords" start="0" size="8" format="unsigned">
         <description>Defines number of data words per channel to be
         read-out. Set it to 0x80 for full readout.</description>
       </field>
     </register>
-
   </group>
 </TrbNetEntity>

diff --git a/xml-db/database/TrbNetEntity.xsd b/xml-db/database/TrbNetEntity.xsd
index 92ef73bc3354a25a8412ed2b465c33f84d43f55f..12c07ec6edf2a34a5aabf4ad85e045e139336936 100644 (file)
--- a/xml-db/database/TrbNetEntity.xsd
+++ b/xml-db/database/TrbNetEntity.xsd
@@ -86,6 +86,10 @@
   <xs:attribute name="continuous"   type="xs:boolean" />
   <xs:attribute name="repeat"       type="xs:positiveInteger" />
   <xs:attribute name="errorflag"    type="xs:boolean" />
+  <!-- unit and scale give information about how to interpret data. a
+       numerical scaling factor and/or a physical unit. E.g.
+       temperature measured in 1/16th degrees will be ".0625" and "°C"
+  -->
   <xs:attribute name="unit"         type="xs:string" />
   <xs:attribute name="scale"        type="xs:double" />
 
@@ -94,9 +98,6 @@
       Simple Elements
       ==============================-->
   <xs:element name="description" type="xs:string" />
-  <!--unit and scale give information about how to interpret data. 
-      a numerical scaling factor and/or a physical unit. E.g. temperature measured
-      in 1/16th degrees will be ".0625" and "°C"-->
 
 
   <!--==============================
@@ -110,14 +111,34 @@
         <xs:choice>
           <xs:element   ref="description"/>
         </xs:choice>
-        <!-- we require that all data is grouped -->
+        <!-- may also contain groups -->
         <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>
+    <!-- although requiring "entity global" unique names usually leads
+         to redundant naming schemes, it hopefully makes "naming confusion"
+         less likely -->
+    <xs:unique name="UniqueFieldNames">
+      <xs:selector xpath=".//field" />
+      <xs:field xpath="@name" />
+    </xs:unique>
+    <xs:unique name="UniqueTrbDataNames">
+      <xs:selector xpath=".//register | .//memory | .//fifo" />
+      <xs:field xpath="@name" />
+    </xs:unique>
+    <!-- consistency of addresses (and start, size of fields) is
+         checked more precisely programmatically -->
+    <xs:unique name="UniqueTrbDataAddressesInTop">
+      <xs:selector xpath="register | memory | fifo" />
+      <xs:field xpath="@address" />
+    </xs:unique>
   </xs:element>
 
   <xs:element name="group">
@@ -144,11 +165,7 @@
       <xs:attribute ref="format" />
       <xs:attribute ref="repeat" />
     </xs:complexType>
-    <xs:unique name="UniqueTrbDataNames">
-      <xs:selector xpath="register | memory | fifo" />
-      <xs:field xpath="@name" />
-    </xs:unique>
-    <xs:unique name="UniqueTrbDataAddresses">
+    <xs:unique name="UniqueTrbDataAddressesInGroup">
       <xs:selector xpath="register | memory | fifo" />
       <xs:field xpath="@address" />
     </xs:unique>
@@ -167,7 +184,7 @@
   <xs:element name="field">
     <xs:complexType>
       <xs:sequence>
-        <!-- description can be omitted if a register or alike only contains 
+        <!-- description can be omitted if a register or alike only contains
              one or several identical fields and the description of them can
              be inherited from the register itself-->
         <xs:choice minOccurs="0">
@@ -191,7 +208,7 @@
       <xs:attribute ref="repeat" />
       <xs:attribute ref="unit" />
       <xs:attribute ref="scale" />
-      <!-- if PERL evaluates this field to false,                             <<<- why false? I'd take true here!
+      <!-- if PERL evaluates this field to true,
            an error is indicated by this field -->
       <xs:attribute ref="errorflag" />
     </xs:complexType>
@@ -204,7 +221,8 @@
 
   <xs:complexType name="basicTrbData">
     <xs:sequence>
-      <xs:choice minOccurs="0">                                              <!--<<<As I wrote, I would like to force it here-->
+      <!-- every TrbData must be described -->
+      <xs:choice>
         <xs:element   ref="description"/>
       </xs:choice>
       <!-- but a data without any fields does not make sense for this

diff --git a/xml-db/xml-db.pl b/xml-db/xml-db.pl
index d4c420a85d3cf8d0ce2c325a2f0d30e2c2480a73..530f64d6cfdeb623a5c5d2a5543b17386554c9cc 100755 (executable)
--- a/xml-db/xml-db.pl
+++ b/xml-db/xml-db.pl
@@ -50,6 +50,7 @@ sub DoSomethingWithDb($) {
 
   my $doc = $db->{'TDC.xml'};
   #my $doc = $db->{'testing.xml'};
+  #my $doc = $db->{'jtag_registers_SPEC.xml'};
   #print Dumper($doc->findnodes('TrbNet')->toDebuggingHash);
   # get the iterator for the document root.
   #my $iter = XML::LibXML::Iterator->new( $doc->documentElement );
@@ -57,8 +58,8 @@ sub DoSomethingWithDb($) {
   my $entityName = $doc->getDocumentElement->getAttribute('name');
   my $entityAddr = hex($doc->getDocumentElement->getAttribute('address'));
 
-  # walk through the document, we select all groups
-  foreach my $groupNode ($doc->findnodes('//group')) {
+  # walk through the document, we select all groups and the top entity
+  foreach my $groupNode ($doc->findnodes('//group | TrbNetEntity')) {
     # determine base name (concatenated by /)
     # and base address (just add all previous offsets)
     my $baseaddress = $entityAddr;