<html>
  <head>
    <title>Port Manager Module Functional Specification</title>
  </head>
  <body>
    <h1>Port Manager Module Functional Specification</h1>
    
    <hr>
      
    <center>
      <table>
	<tr>
	  <td>Drawing Number:</td>
          <td>2309,331/FS</td>
	</tr>
	<tr>
	  <td>Issue:</td>
          <td>B</td>
	</tr>
	<tr>
	  <td>Date:</td>
          <td><!-- Begin date -->09 April, 1999<!-- End date --></td>
	</tr>
	<tr>
	  <td>Previous issue:</td>
          <td>A</td>
        </tr>
	<tr>
	  <td>Status:</td>
          <td>Draft</td>
	</tr>
	<tr>
	  <td>Change:</td>
          <td>&nbsp</td>
	</tr>
	<tr>
	  <td>Author:</td>
          <td>Neil Turton</td>
	</tr>
	<tr>
	  <td>Master Format:</td>
          <td>HTML</td>
	</tr>
	<tr>
	  <td>Classification:</td>
	  <td>Secret</td>
      </table>
    </center>

    <hr>

    <h1>Contents</h1>
    <ul>
      <!-- Begin contents -->
	<li><a name="C_1" href="#S_1">
	  1 Introduction</a></li>
	<li><a name="C_1_1" href="#S_1_1">
	  1.1 Purpose and scope</a></li>
	<li><a name="C_1_2" href="#S_1_2">
	  1.2 Change history</a></li>
	<li><a name="C_2" href="#S_2">
	  2 Outstanding Issues</a></li>
	<li><a name="C_3" href="#S_3">
	  3 Technical Background</a></li>
	<li><a name="C_4" href="#S_4">
	  4 User interface</a></li>
	<li><a name="C_5" href="#S_5">
	  5 Programmer interface</a></li>
	<li><a name="C_5_1" href="#S_5_1">
	  5.1 PortMan_AccessBit (&amp;52D80)</a></li>
	<li><a name="C_5_2" href="#S_5_2">
	  5.2 Service_PortMan (&amp;C2)</a></li>
	<li><a name="C_6" href="#S_6">
	  6 Data interchange</a></li>
	<li><a name="C_7" href="#S_7">
	  7 Data formats</a></li>
	<li><a name="C_7_1" href="#S_7_1">
	  7.1 Tags file format</a></li>
	<li><a name="C_7_2" href="#S_7_2">
	  7.2 Tags file flags</a></li>
	<li><a name="C_7_3" href="#S_7_3">
	  7.3 Defined tags</a></li>
	<li><a name="C_7_4" href="#S_7_4">
	  7.4 STB3 Tags file contents</a></li>
	<li><a name="C_8" href="#S_8">
	  8 External dependencies</a></li>
	<li><a name="C_9" href="#S_9">
	  9 Acceptance test</a></li>
	<li><a name="C_10" href="#S_10">
	  10 Non-compliances</a></li>
	<li><a name="C_11" href="#S_11">
	  11 Development test strategy</a></li>
	<li><a name="C_12" href="#S_12">
	  12 Product organization</a></li>
	<li><a name="C_13" href="#S_13">
	  13 Future enhancements</a></li>
	<li><a name="C_14" href="#S_14">
	  14 Glossary</a></li>
	<li><a name="C_15" href="#S_15">
	  15 References</a></li>
<!-- End contents -->
    </ul>

    <hr>

    <h2><a name="S_1" href="#C_1">1 Introduction</a></h2>
    <h3><a name="S_1_1" href="#C_1_1">1.1 Purpose and scope</a></h3>
    <p>
      This document specifies the operation of the Port Manager Module
      for RISC OS.  It is intended for writers of software which uses
      the Port Manager and people writing unit test cases for this
      component.
    </p>

    <h3><a name="S_1_2" href="#C_1_2">1.2 Change history</a></h3>
    <center>
      <table border="1" width="80%">
	<tr>
	  <th width="10%">Date</th>
	  <th width="10%">Issue</th>
	  <th width="60%">Changes</th>
	</tr>
	<tr>
	  <td>01 March, 1999</td>
	  <td align="center">A</td>
	  <td>First issue.</td>
	</tr>
	<tr>
	  <td>09 April, 1999</td>
	  <td align="center">B</td>
	  <td>
	    <p>
	      Modified following review.  Documented the service call.
	      Added STB3 tags file contents.  Added section on FIQ
	      support.  Minor edits.
	    </p>
	  </td>
	</tr>
      </table>
    </center>

    <h2><a name="S_2" href="#C_2">2 Outstanding Issues</a></h2>
    <p>
      There are no outstanding issues.
    </p>

    <h2><a name="S_3" href="#C_3">3 Technical Background</a></h2>
    <p>
      The IOMD has a general purpose 8-bit IO port which is used for
      miscellaneous functions such as controlling LEDs, and
      configuring software for PAL/NTSC machines.  Each bit can be
      used as either an input or an output.  By it's very nature, it
      is used by more than one piece of software, so they must
      cooperate in their usage.  Software using input bits will cause
      no problem, since they simply read the port and use the read
      value.  Software using output bits need to ensure that when they
      write to the port they preserve all the output bits, and write a
      1 to the input bits (due to the way the port works).
    </p>

    <p>
      On the STB3, the current state of some of the output bits on the
      IOMD GPIO port (the SCART control bits) cannot be read from
      software.  This means that software wishing to write to other
      bits, and preserve the SCART control bits cannot simply read the
      IO port to determine their current state.  Instead, software
      must keep track of the current state of the port.
    </p>
    
    <p>
      The Port Manager module will keep track of the current state of
      the IOMD GPIO port, and allow other software to modify
      individual bits without affecting the state of the other bits.
      It is recomended that all GPIO access be done through the Port
      Manager to ensure a consistant view of the port.
    </p>

    <h2><a name="S_4" href="#C_4">4 User interface</a></h2>
    <p>
      This module has no user interface.
    </p>

    <h2><a name="S_5" href="#C_5">5 Programmer interface</a></h2>
    <p>
      On module initialisation the Port Manager module will reset the
      GPIO port to it's power-on state (all bits set).  Other software
      may then use the following SWIs provided by Port Manager.  All
      SWIs return a standard RISC&nbsp;OS error block in
      <code>r0</code> and set the V bit if the operation failed.
    </p>

    <h3><a name="S_5_1" href="#C_5_1">5.1 PortMan_AccessBit (&amp;52D80)</a></h3>
    
    <h4><a name="S_5_1_1" href="#C_5_1_1">5.1.1 On entry</a></h4>
    <table border="1">
      <tr>
	<th width="20%">Register</th>
	<th width="60%">Meaning</th>
      </tr>
      <tr>
	<td align="center"><code>r0</code></td>
	<td>Flags.</td>
      </tr>
      <tr>
	<td align="center"><code>r1</code></td>
	<td>Pointer to tag name - NUL terminated.</td>
      </tr>
    </table>
    
    <h4><a name="S_5_1_2" href="#C_5_1_2">5.1.2 Flags</a></h4>
    <table border="1">
      <tr>
	<th width="20%">Bit number</th>
	<th width="60%">Meaning when set</th>
      </tr>
      
      <tr>
	<td align="center"><code>0</code></td>
	<td>The bit should be masked.</td>
      </tr>
      <tr>
	<td align="center"><code>1</code></td>
	<td>The bit should be toggled.</td>
      </tr>
    </table>

    <p>
      All other bits should be <strong>zero</strong> on entry.
    </p>

    <h4><a name="S_5_1_3" href="#C_5_1_3">5.1.3 On exit</a></h4>
    <table border="1">
      <tr>
	<th width="20%">Register</th>
	<th width="60%">Meaning</th>
      </tr>
      <tr>
	<td align="center"><code>r0</code> </td>
	<td>Output flags.</td>
      </tr>
    </table>

    <p>
      All other registers are preserved.
    </p>

    <h4><a name="S_5_1_4" href="#C_5_1_4">5.1.4 Output flags</a></h4>
    <table border="1">
      <tr>
	<th width="20%">Bit</th>
	<th width="60%">Meaning when set</th>
      </tr>
      
      <tr>
	<td align="center"><code>0</code></td>
	<td>The old value of the bit.</td>
      </tr>
      
      <tr>
	<td align="center"><code>1</code></td>
	<td>The new value of the bit.</td>
      </tr>
    </table>

    <p>
      All other registers are preserved.
    </p>

    <h4><a name="S_5_1_5" href="#C_5_1_5">5.1.5 Effect</a></h4>
    <p>
      This SWI will modify a single bit which is under the control of
      the module if it is an output bit.  If the specified bit is an
      input bit, the value of the bit is not changed.  The bit is
      specified by a tag name which is pointed to by <code>r1</code>
      on entry.  The logical value of the bit is first cleared if bit
      <code>0</code> of flags is set.  The value is then toggled if
      bit <code>1</code> of flags is set. The original value of the
      bit is returned in <code>r0</code>.  Note: The meaning of the
      logical state of the bit is defined by the tag and may be
      different from the value of the bit in hardware.
    </p>

    <h4><a name="S_5_1_6" href="#C_5_1_6">5.1.6 Errors</a></h4>
    <p>
      The following errors are defined.
    </p>
    <table border="1">
      <tr>
	<th>Error number</th>
	<th>Meaning</th>
      </tr>
      
      <tr>
	<td align="center">&amp;816900</td>
	<td>The specified tag does not exist.</td>
      </tr>
    </table>

    <h3><a name="S_5_2" href="#C_5_2">5.2 Service_PortMan (&amp;C2)</a></h3>
    <p>
      The Port Manager notifies modules of a change of state using
      the service call <code>Service_PortMan</code> as follows.
    </p>

    <table border="1">
      <tr>
        <th width="20%">Register</th>
        <th width="60%">Contents</th>
      </tr>

      <tr>
        <td><code>r0</code></td>
        <td>Reason code.</td>
      </tr>

      <tr>
        <td><code>r1</code></td>
        <td>Service call number (&amp;C2).</td>
      </tr>
    </table>

    <p>
      Modules which do not understand the reason code should pass
      the service call on.  The current reason codes are listed below.
    </p>

    <h4><a name="S_5_2_1" href="#C_5_2_1">5.2.1 PORTMAN_SERVICE_STARTING (r0=&amp;0).</a></h4>
    <p>
      The Port Manager service call is issued with reason code
      <code>0</code> on a callback after it is initialised.  This is
      to allow modules to issue Port Manager SWIs to initialise the
      GPIO port.  Modules should not claim this service call.  Since
      this service call is issued on a callback it is possible to
      issue SWIs during the service call.  It should also be noted
      that it is possible to issue Port Manager SWIs before the
      service call is delivered, or even for the service call to be
      omitted (if for example the Port Manager module is killed before
      the callback occurs.
    </p>

    <h4><a name="S_5_2_2" href="#C_5_2_2">5.2.2 PORTMAN_SERVICE_DYING (r0=&amp;1).</a></h4>
    <p>
      The Port Manager service call is issued with reason code
      <code>1</code> during it's module finalisation routine to inform
      modules that it's SWIs are no longer available.  It may be
      issued without issuing PORTMAN_SERVICE_STARTING if callbacks do
      not go off between module initialisation and module
      finalisation.  It is issued anyway since Port Manager SWIs may
      have been issued.  Port Manager SWIs may not be issued during
      this service call.
    </p>

    <h2><a name="S_6" href="#C_6">6 Data interchange</a></h2>

    <h2><a name="S_7" href="#C_7">7 Data formats</a></h2>
    <h3><a name="S_7_1" href="#C_7_1">7.1 Tags file format</a></h3>
    <p>
      This module is configured using a tags file.  The file is a set
      of lines containing colon separated fields.  The following
      fields are defined.
    </p>
    
    <table border="1">
      <tr>
	<th>Field number</th>
	<th>Default if optional</th>
	<th>Meaning</th>
      </tr>
      
      <tr>
	<td align="center"><code>1</code></td>
	<td><em>Mandatory</em></td>
	<td>The name of the tag to be matched.</td>
      </tr>
      
      <tr>
	<td align="center"><code>2</code></td>
	<td><em>Mandatory</em></td>
	<td>Specifies which bit the tag refers to.</td>
      </tr>
      
      <tr>
	<td align="center"><code>3</code></td>
	<td><code>0</code></td>
	<td>Specifies which port should be used.</td>
      </tr>
      
      <tr>
	<td align="center"><code>4</code></td>
	<td><code>0</code></td>
	<td>Flags.</td>
      </tr>
    </table>

    <h3><a name="S_7_2" href="#C_7_2">7.2 Tags file flags</a></h3>
    <p>
      The flags field in the tags file has the following meaning.
    </p>

    <table border="1">
      <tr>
	<th>Flag bit</th>
	<th>Meaning</th>
      </tr>
      
      <tr>
	<td align="center"><code>0</code></td>
	<td>Bit is inverted in hardware.</td>
      </tr>
      
      <tr>
	<td align="center"><code>1</code></td>
	<td>Bit is an output bit.</td>
      </tr>
    </table>
    
    <h3><a name="S_7_3" href="#C_7_3">7.3 Defined tags</a></h3>
    <p>
      The following tags are currently defined.
    </p>   

    <table border="1" width="80%">
      <tr>
	<th width="20%">Tag name</th>
	<th width="10%">Type</th>
	<th width="50%">Meaning of bit when set</th>
      </tr>
      
      <tr>
	<td align="center"><code>MPEG_Fitted</code></td>
	<td align="center">Input</td>
	<td>MPEG Hardware is fitted.</td>
      </tr>
      
      <tr>
	<td align="center"><code>LED_Red</code></td>
	<td align="center">Output</td>
	<td>The red LED is on.</td>
      </tr>
      
      <tr>
	<td align="center"><code>LED_Green</code></td>
	<td align="center">Output</td>
	<td>The green LED is on (this is the LED under software
          control, not the IR activity LED found on STBs).</td>
      </tr>
      
      <tr>
	<td align="center"><code>SCART_TV</code></td>
	<td align="center">Output</td>
	<td>
	  TV mode should be asserted on the SCART connector (not
	  external mode).
	</td>
      </tr>

      <tr>
	<td align="center">NTSC</td>
	<td align="center">Input</td>
	<td>
	  Indicates that this device is configured to produce NTSC
	  display output.
	</td>
      </tr>
  
      <tr>
	<td align="center">Interlace_Odd</td>
	<td align="center">Input</td>
	<td>Current field is odd.</td>
      </tr>
      
      <tr>
	<td align="center"><code>SCART_CVBS</code></td>
	<td align="center">Output</td>
	<td>
	  CVBS should be selected on the SCART connector (not RGB
	  select).
	</td>
      </tr>
      
      <tr>
	<td align="center"><code>Watchdog</code></td>
	<td align="center">Output</td>
	<td>Inform watchdog timer that the machine is in standby.</td>
      </tr>
  </table>

    <h3><a name="S_7_4" href="#C_7_4">7.4 STB3 Tags file contents</a></h3>
    <p>
      The Tags file for STB3 is as follows.
    </p>

    <pre>
MPEG_Fitted:    0:0:0
LED_Red:        1:0:2
LED_Green:      2:0:2
SCART_TV:       3:0:2
NTSC:           4:0:0
Interlace_Odd:  5:0:0
SCART_CVBS:     6:0:2
Watchdog:       7:0:2
    </pre>
    
    <h2><a name="S_8" href="#C_8">8 External dependencies</a></h2>
    <p>
      There are no external dependencies.
    </p>

    <h2><a name="S_9" href="#C_9">9 Acceptance test</a></h2>
    <p>
      The module will be accepted if it correctly implements all of the
      functionality described in this specification.
    </p>
    
    <h2><a name="S_10" href="#C_10">10 Non-compliances</a></h2>
    <p>
      There are no non-compliances.
    </p>

    <h2><a name="S_11" href="#C_11">11 Development test strategy</a></h2>
    <p>
      A program will be written to ensure the SWI interface is
      consistent when accessing both readable and non-readable bits.
      For readable bits it will ensure that the changes it makes have
      the correct effect on the hardware.  It will report any
      inconsistencies found.  It may assume there is no other software
      accessing the GPIO port.  It will also ensure that the service
      call is dispatched correctly.
    </p>

    <h2><a name="S_12" href="#C_12">12 Product organization</a></h2>
    <p>
      The product is organized as a RISC OS relocatable module.  It
      selects an appropriate tags file based on the machine system
      variable.
    </p>

    <h2><a name="S_13" href="#C_13">13 Future enhancements</a></h2>
    <p>
      The module may be extended to allow other modules to register
      with the Port Manager to give access to ports which they can
      control.  A bit can then be moved between ports by simply
      changing the tags file.
    </p>

    <p>
      The Port Manager my also be enhanced by providing a SWI to
      modify multiple bits in the same call.  This would involve a
      list of tags, a word containing the mask, and a word containing
      a value to XOR.
    </p>

    <p>
      The current interface can't be used to access the GPIO port when
      the processor is in FIQ mode, and SWI dispatching takes longer than
      would be acceptable if FIQs were being used.  An interface may be
      added to allow a FIQ routine to access the GPIO port soft-copy
      directly, and request the locations of bits.  This would only work
      for bits which are actually on the GPIO port.
    </p>

    <h2><a name="S_14" href="#C_14">14 Glossary</a></h2>
    <dl>
      <dt>CPU</dt>   <dd>Central Processor Unit.</dd>
      <dt>GPIO</dt>  <dd>General Purpose Input/Output</dd>
      <dt>IOMD</dt>  <dd>IO and Memory controller chip which has been
        incorporated into the 7500 and 7500FE CPUs.
    </dl>

    <h2><a name="S_15" href="#C_15">15 References</a></h2>
    
  </body>
</html>
