The XML Format Used by the Data Master

The DM uses an XML format to describe a schedule. Presently (09/2014), this format depends on implementation details. A (non-realistic) example is given at the end of this page.

Overview

Current data format uses the following data structure:

---

• Page
  • Plan A
    • chain 1
      • msg 0
      • ...
      • msg n
    • ...
    • chain m
  • Plan B

---

Time is in units of 1 ns.

Important: Please do not confuse the execution of "tasks" on the CPU with the execution of commands at the timing receivers. The data master has to send the messages ahead of time. This offset - ahead-interval - is considered by the data master and presently has a length of 250us. This implies: If a chain starts with a condition, the first message must not have an offset smaller than the ahead-interval.

Page

A schedule is contained in a page. The DM has an active and a passive page. The active page is used for execution, while the passive page can be used to upload or modify a new schedule. A page includes one or more plans. One plan is the start plan or default plan. Execution starts with this plan. Alternative plans can be specified and might be executed depending on (external) conditions.

<page>
  <meta>
    <startplan>A</startplan> 
    <altplan>B</altplan>       
  </meta>
  
  <plan>
    ...
  </plan>
  <plan>
    ...
   </plan>
</page>

Plan

A plan has a name (as a comment), a start time and chains. The start time specifies date and time of execution start. This allows to schedule the absolute execution time. If the time specified is in the past, chain execution starts immediately. Chains within a plan are executed in the order specified. Each plan has a dedicated control register.

If a chain has its branchpoint enabled, the branchpoint is checked a) at the end of the chain or b) if a condition comparison yields "false" (see below). In case of a branchpoint, the control register is checked. The control register contains an address. If the value of the address eq "0x0", the branchpoint is ignored and execution continues with the next chain. If the value of the address neq "0x0", program execution continues at the address specified in the register (this is similar to a goto statement). The concept of a branchpoint allows to jump to a different plan (or a different chain). By this, the data master can quickly jump to a different pre-defined schedule upon external events like a change of interlock conditions. A plan will loop (not loop) if lastjump has a value of "self" ("idle"). In case a plan loops, the number of repetitions is specified in the last chain of that plan.

   <plan>
      <!-- Plan A -->
      <meta>
         <starttime>9999999</starttime>
         <lastjump>idle</lastjump>
      </meta>

      <chain>
         ...
      </chain>
      <chain>
         ...
      </chain>
      ...
   </plan>

Chain

A chain is sequence of elements that are executed as a series that can not be interrupted. A chain contains a meta element and zero, one or more messages.

      <chain>
         <!-- Chain B2 -->
         <meta>
            ...
         </meta>
         <msg>
            ...
         </msg>
         <msg>
            ...
         </msg>
      </chain>

Meta Element of a Chain

The meta element has mandatory and optional elements. An example including all possible fields is given below.

         <meta>
            <rep>10</rep>
            <period>2000</period>
            <branchpoint>yes</branchpoint>
            <condition>
               <source>shared</source>
               <pattern>0xcafebabe</pattern>
               <mask>0xffffffff</mask>
               <always>no</always>
            </condition>
            <signal>
               <destination>shared</destination>
               <cpu>1</cpu>
               <value>0xce42</value>
               <always>yes</always>
            </signal>
         </meta>

The following table describes the relevant elements.

Element	Optional	Description
rep		number of repetitions
		-1: repeat forever
		0: skip, only evaluate branchpoint
		1..N: n of iterations
period		length of a chain - if conditional, period must be larger than the ahead-interval
branchpoint		"yes"/"no": Chain has a branchpoint
condition	X	source: "shared"/"MSI"
		pattern: must be fulfilled
		mask: masks value of the source
signal	X	writes a value to a CPUs control register at the end of a chain
		destination: "shared"/"MSI" (MSI is queued, shared is not)
		cpu: number of CPU
		value: 32 bit value to be written to the cpu

Signal
When a chain is supposed to sent a signal to another CPU, the signal is sent when the chain starts. If the chain must fulfil a condition first, the signal is sent after the condition is fulfilled. Implicit: A signal is sent for each iteration of a chain. When the signal is sent via shared memory, the sending chain also includes the timestamp of the moment, when the current iteration will end (start time + period length). Via MSI, the recipient will use the time it received the MSI. Condition
When a chain waits on a condition, it waits until the condition becomes true or there is a branchpoint.

• When the condition becomes true, it is never checked again.
• After the condition became true, the chain starts whenever one of the following first becomes true:
  • the actual time equals the time specified in the "header" of the chain.
  • the actual time equals the time that was received together with the signal
  • while waiting for the right moment, the branchpoint is always checked too

Message

Background information: In case a timing receiver has been configured to trigger an action upon receiving a message with a specific ID, the action will be executed at the time specified by the start time of a chain plus the offset specified in the message.

An example of a command message is given below.

         <msg>
            <!-- Msg B0B -->
            <id>
               <FID>2</FID>
               <GID>3</GID>
               <EVTNO>1</EVTNO>
               <SID>5</SID>
               <BPID>6</BPID>
            </id>
            <par>0xdeadfa14</par>
            <tef>0</tef>
            <offs>500</offs>
         </msg>

Please note:

• A chain may contain 0..N messages.
• All elements except offset are described here.
• The value given by offset (offs) is added to the absolute time of the beginning of the chain. The absolute time obtained as result defines the time when the execution is triggered.

Example of a Schedule

Simple Heartbeat with two messages and one branchbpoint

<page>
   <meta>
      <startplan>A</startplan>
      <altplan>A</altplan>
   </meta>
   
   <plan>
      <!-- Plan A, normal operation -->
      <meta>
         <starttime>0</starttime>
         <lastjump>idle</lastjump>
      </meta>  
      <chain>
         <!-- Cycle A0, entry -->
         <meta>
            <rep>5000</rep>
            <period>100000</period>
            <branchpoint>yes</branchpoint>
         </meta>
         <msg>
            <!-- Msg A0A -->
            <id>
               <FID>0</FID>
               <GID>4095</GID>
               <EVTNO>1</EVTNO>
               <SID>0</SID>
               <BPID>0</BPID>
            </id>
            <par>0xdead0561</par>
            <tef>000</tef>
            <offs>000000000</offs>
         </msg>
         <msg>
             <!-- Msg A0B -->
            <id>
               <FID>0</FID>
               <GID>4095</GID>
               <EVTNO>2</EVTNO>
               <SID>0</SID>
               <BPID>0</BPID>
            </id>
            <par>0xdead0562</par>
            <tef>000</tef>
            <offs>000000008</offs>
         </msg>
      </chain>
   </plan>
</page>

Further Information

• The format of command messages is described here
• Some information on groups is given here.

-- DietrichBeck - 29 Sep 2014