# Port Manager Module Functional Specification

Drawing Number: | 2309,331/FS
Issue: | B
Date: | 09 April, 1999
Previous issue: | A
Status: | Draft
Change: |
Author: | Neil Turton
Master Format: | HTML
Classification: | Secret

# Contents

- 1 Introduction
- 1.1 Purpose and scope
- 1.2 Change history
- 2 Outstanding Issues
- 3 Technical Background
- 4 User interface
- 5 Programmer interface
- 5.1 PortMan_AccessBit (&52D80)
- 5.2 Service_PortMan (&C2)
- 6 Data interchange
- 7 Data formats
- 7.1 Tags file format
- 7.2 Tags file flags
- 7.3 Defined tags
- 7.4 STB3 Tags file contents
- 8 External dependencies
- 9 Acceptance test
- 10 Non-compliances
- 11 Development test strategy
- 12 Product organization
- 13 Future enhancements
- 14 Glossary
- 15 References

## 1 Introduction

### 1.1 Purpose and scope

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.

### 1.2 Change history

Date | Issue | Changes
--- | --- | ---
01 March, 1999 | A | First issue.
09 April, 1999 | B | Modified following review. Documented the service call. Added STB3 tags file contents. Added section on FIQ support. Minor edits.

## 2 Outstanding Issues

There are no outstanding issues.

## 3 Technical Background

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).

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.

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.

## 4 User interface

This module has no user interface.

## 5 Programmer interface

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 OS error block in `r0` and set the V bit if the operation failed.

### 5.1 PortMan_AccessBit (&52D80)

#### 5.1.1 On entry

Register | Meaning
--- | ---
`r0` | Flags.
`r1` | Pointer to tag name - NUL terminated.

#### 5.1.2 Flags

Bit number | Meaning when set
--- | ---
`0` | The bit should be masked.
`1` | The bit should be toggled.

All other bits should be zero on entry.

#### 5.1.3 On exit

Register | Meaning
--- | ---
`r0` | Output flags.

All other registers are preserved.

#### 5.1.4 Output flags

Bit | Meaning when set
--- | ---
`0` | The old value of the bit.
`1` | The new value of the bit.

All other registers are preserved.

#### 5.1.5 Effect

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 `r1` on entry. The logical value of the bit is first cleared if bit `0` of flags is set. The value is then toggled if bit `1` of flags is set. The original value of the bit is returned in `r0`. 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.

#### 5.1.6 Errors

The following errors are defined.

Error number | Meaning
--- | ---
&816900 | The specified tag does not exist.

### 5.2 Service_PortMan (&C2)

The Port Manager notifies modules of a change of state using the service call `Service_PortMan` as follows.

Register | Contents
--- | ---
`r0` | Reason code.
`r1` | Service call number (&C2).

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

#### 5.2.1 PORTMAN_SERVICE_STARTING (r0=&0).

The Port Manager service call is issued with reason code `0` 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.

#### 5.2.2 PORTMAN_SERVICE_DYING (r0=&1).

The Port Manager service call is issued with reason code `1` 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.

## 6 Data interchange

## 7 Data formats

### 7.1 Tags file format

This module is configured using a tags file. The file is a set of lines containing colon separated fields. The following fields are defined.

Field number | Default if optional | Meaning
--- | --- | ---
`1` | Mandatory | The name of the tag to be matched.
`2` | Mandatory | Specifies which bit the tag refers to.
`3` | `0` | Specifies which port should be used.
`4` | `0` | Flags.

### 7.2 Tags file flags

The flags field in the tags file has the following meaning.

Flag bit | Meaning
--- | ---
`0` | Bit is inverted in hardware.
`1` | Bit is an output bit.

### 7.3 Defined tags

The following tags are currently defined.

Tag name | Type | Meaning of bit when set
--- | --- | ---
`MPEG_Fitted` | Input | MPEG Hardware is fitted.
`LED_Red` | Output | The red LED is on.
`LED_Green` | Output | The green LED is on (this is the LED under software control, not the IR activity LED found on STBs).
`SCART_TV` | Output | TV mode should be asserted on the SCART connector (not external mode).
NTSC | Input | Indicates that this device is configured to produce NTSC display output.
Interlace_Odd | Input | Current field is odd.
`SCART_CVBS` | Output | CVBS should be selected on the SCART connector (not RGB select).
`Watchdog` | Output | Inform watchdog timer that the machine is in standby.

### 7.4 STB3 Tags file contents

The Tags file for STB3 is as follows.

    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

## 8 External dependencies

There are no external dependencies.

## 9 Acceptance test

The module will be accepted if it correctly implements all of the functionality described in this specification.

## 10 Non-compliances

There are no non-compliances.

## 11 Development test strategy

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.

## 12 Product organization

The product is organized as a RISC OS relocatable module. It selects an appropriate tags file based on the machine system variable.

## 13 Future enhancements

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.

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.

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.

## 14 Glossary

CPU
  Central Processor Unit.
GPIO
  General Purpose Input/Output
IOMD
  IO and Memory controller chip which has been incorporated into the 7500 and 7500FE CPUs.

## 15 References