From a2945327a0c4dc3aed8c8b2c376818311caacd31 Mon Sep 17 00:00:00 2001
From: Jan Michel <j.michel@gsi.de>
Date: Sun, 30 Jun 2013 00:16:34 +0200
Subject: [PATCH] changed granularity to unit / scale. And some minor changes

---
 xml-db/database/TDC.xml                 | 21 +++++---------
 xml-db/database/TrbNetEntity.xsd        | 37 ++++++++++++-------------
 xml-db/database/jtag_registers_SPEC.xml |  5 +++-
 xml-db/xml-db.pl                        |  2 +-
 4 files changed, 30 insertions(+), 35 deletions(-)

diff --git a/xml-db/database/TDC.xml b/xml-db/database/TDC.xml
index 2070801..cf6af06 100644
--- a/xml-db/database/TDC.xml
+++ b/xml-db/database/TDC.xml
@@ -50,15 +50,13 @@
     </memory>
 
     <register name="TriggerWindow" address="0003" purpose="status">
-      <field name="Before" start="0" size="11" format="time">
+      <field name="Before" start="0" size="11" format="time" unit="ns" scale="5">
         <description>Trigger window width BEFORE the trigger with
         granularity of 5 ns</description>
-        <granularity>5</granularity>
       </field>
-      <field name="After" start="16" size="11" format="time">
+      <field name="After" start="16" size="11" format="time" unit="ns" scale="5">
         <description>Trigger window width AFTER the trigger with
         granularity of 5 ns</description>
-        <granularity>5</granularity>
       </field>
       <field name="Enable" start="31" format="boolean">
         <description>Trigger window enabled?</description>
@@ -120,18 +118,16 @@
     </register>
 
     <register name="Idle" address="000c">
-      <field name="Time" start="0" size="24" format="time">
+      <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>
-        <granularity>10</granularity>
       </field>
     </register>
     
     <register name="Wait" address="000d">
-      <field name="Time" start="0" size="24" format="time">
+      <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>
-        <granularity>10</granularity>
       </field>
     </register>
 
@@ -149,10 +145,9 @@
     </register>
 
     <register name="Readout" address="0010">
-      <field name="Time" start="0" size="24" format="time">
+      <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>
-        <granularity>10</granularity>
       </field>
     </register>
 
@@ -197,15 +192,13 @@
     </register>
 
     <register name="TriggerWindow" address="0001">
-      <field name="Before" start="0" size="11" format="time">
+      <field name="Before" start="0" size="11" format="time" unit="ns" scale="5">
         <description>Trigger window width BEFORE the trigger with
         granularity of 5 ns</description>
-        <granularity>5</granularity>
       </field>
-      <field name="After" start="16" size="11" format="time">
+      <field name="After" 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>
-        <granularity>5</granularity>
       </field>
       <field name="Enable" start="31" format="boolean">
         <description>Trigger window enable</description>
diff --git a/xml-db/database/TrbNetEntity.xsd b/xml-db/database/TrbNetEntity.xsd
index e1aff46..92ef73b 100644
--- a/xml-db/database/TrbNetEntity.xsd
+++ b/xml-db/database/TrbNetEntity.xsd
@@ -24,7 +24,7 @@
 
   <xs:simpleType name="modetype">
     <xs:restriction base="xs:string">
-      <xs:pattern value="r|w|rw|b"/>
+      <xs:pattern value="(r|w|rw)b?"/>
       <!-- (r)ead and /or (w)rite, plus maybe (b)lock, if a
            no-more-data from this registers transports some vital
            information -->
@@ -34,13 +34,11 @@
   <xs:simpleType name="purposetype">
     <!-- config: setup some behaviour
          trigger: register which starts some kind of operation of the hardware
-         status: slowly changing information
-         statistics: quickly changing information
+         status: shows the current status of components. E.g. temperature or the state of a state machine
+         statistics: statistical information like event counter or amount of data transferred
          ***
          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)
+         they both give some information about the system.
     -->
     <xs:restriction base="xs:string">
       <xs:enumeration value="config"/>
@@ -79,7 +77,7 @@
   <xs:attribute name="name"         type="nametype" />
   <xs:attribute name="address"      type="addresstype" />
   <xs:attribute name="mode"         type="modetype"  />
-  <xs:attribute name="purpose"     type="purposetype" />
+  <xs:attribute name="purpose"      type="purposetype" />
   <xs:attribute name="start"        type="bittype" />
   <xs:attribute name="size"         type="xs:positiveInteger" />
   <xs:attribute name="defaultValue" type="valuetype" />
@@ -88,13 +86,17 @@
   <xs:attribute name="continuous"   type="xs:boolean" />
   <xs:attribute name="repeat"       type="xs:positiveInteger" />
   <xs:attribute name="errorflag"    type="xs:boolean" />
+  <xs:attribute name="unit"         type="xs:string" />
+  <xs:attribute name="scale"        type="xs:double" />
 
 
   <!--==============================
       Simple Elements
       ==============================-->
   <xs:element name="description" type="xs:string" />
-  <xs:element name="granularity" type="xs:double" />
+  <!--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"-->
 
 
   <!--==============================
@@ -165,7 +167,10 @@
   <xs:element name="field">
     <xs:complexType>
       <xs:sequence>
-        <xs:choice>
+        <!-- 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">
           <xs:element   ref="description"/>
         </xs:choice>
         <xs:choice minOccurs="0" maxOccurs="unbounded">
@@ -174,12 +179,6 @@
                other formats... -->
           <xs:element   ref="enumItem" />
         </xs:choice>
-        <xs:choice minOccurs="0" maxOccurs="unbounded">
-          <!-- granularity is only meaningful for format="time"
-               fields, however we don't complain if there are some for
-               other formats... -->
-          <xs:element ref="granularity" />
-        </xs:choice>
       </xs:sequence>
 
       <xs:attribute ref="name" use="required" />
@@ -190,7 +189,9 @@
       <xs:attribute ref="defaultValue" />
       <xs:attribute ref="format" />
       <xs:attribute ref="repeat" />
-      <!-- if PERL evaluates this field to false,
+      <xs:attribute ref="unit" />
+      <xs:attribute ref="scale" />
+      <!-- if PERL evaluates this field to false,                             <<<- why false? I'd take true here!
            an error is indicated by this field -->
       <xs:attribute ref="errorflag" />
     </xs:complexType>
@@ -203,9 +204,7 @@
 
   <xs:complexType name="basicTrbData">
     <xs:sequence>
-      <!-- in contrast to the "field" elements, a description is not
-           required here -->
-      <xs:choice minOccurs="0">
+      <xs:choice minOccurs="0">                                              <!--<<<As I wrote, I would like to force it here-->
         <xs:element   ref="description"/>
       </xs:choice>
       <!-- but a data without any fields does not make sense for this
diff --git a/xml-db/database/jtag_registers_SPEC.xml b/xml-db/database/jtag_registers_SPEC.xml
index 190bead..bbd649f 100644
--- a/xml-db/database/jtag_registers_SPEC.xml
+++ b/xml-db/database/jtag_registers_SPEC.xml
@@ -148,6 +148,7 @@
            address="0000"  size="8"  repeat="5"  purpose="status"  mode="r"  continuous="true">
       <register  name="JtagErrorCount1"
                 address="0002" purpose="status" mode="r" >
+        <description>Error counters for read and write operations on the JTAG chain</description>
         <field name="ErrorsReadId"
                start="0"   size="16"  mode="r"  purpose="status"  format="integer" >
           <description>Number of read errors during "read id" operation</description>
@@ -159,6 +160,7 @@
       </register>
       <register  name="JtagErrorCount2"
                 address="0003" purpose="status" mode="r" >
+        <description>Error counters for read and write operations on the JTAG chain</description>
         <field name="ErrorsDataChanged"
                start="0"   size="16"  mode="r"  purpose="status"  format="integer" >
           <description>Number of times data read back from the sensor was not identical to the data written to the sensor.</description>
@@ -170,13 +172,14 @@
       </register>
       <register  name="JtagRunCounter"
                 address="0004" purpose="status" mode="r" >
+        <description>Number of times the JTAG controller run a full sequence</description>
         <field name="JtagRunCounter"
                start="0"   size="32"  mode="r"  purpose="status"  format="integer" >
-          <description>Number of times the JTAG controller run a full sequence</description>
         </field>
       </register>
       <register  name="JtagStatusFlags"
                 address="0005" purpose="status" mode="r" >
+        <description>Status flags of the JTAG chain</description>
         <field name="JtagStarted"
                start="0"   size="1"  mode="r"  purpose="status"  format="boolean" >
           <description>JTAG has been started</description>
diff --git a/xml-db/xml-db.pl b/xml-db/xml-db.pl
index fe3858a..d4c420a 100755
--- a/xml-db/xml-db.pl
+++ b/xml-db/xml-db.pl
@@ -3,7 +3,7 @@ use strict;
 use warnings;
 
 use XML::LibXML;
-use XML::LibXML::Debugging;
+#use XML::LibXML::Debugging;
 #use XML::LibXML::Iterator;
 use Getopt::Long;
 use Pod::Usage;
-- 
2.43.0