DCI4 Statistic Interface

Plus points

• Simplicity of implementation
• Single generic statistics display program
• No essential central information that needs frequent updating
• Information is for presentation to humans primarily
• Atomic operations without any latching mechanisms
• Well behaved with multiple gatherers
• Well behaved if a supplier unexpectedly disappears
• Virtually stateless communication

Minus points

• Not re-entrant - callbacks or user mode code only
• Restrictive string model
• Polled interface, rather than event driven
• Only simple flat structure to statistics
• Only really suitable for human display

Basics of operation

A piece of software that wishes to offer statistics is termed a "supplier". A piece of software that obtains statistics from a supplier and presents them to the user is termed a "gatherer", and the operation it performs is often referred to as "enumerating the statistics". There are typically more suppliers than gatherers in a system.

As part of its normal operations, a supplier maintains a set of statistics. A gatherer, typically upon user invocation, enumerates the available suppliers, enumerates the statistics supplied by each supplier and then presents this information to the user. More dynamic presentation is also possible. A supplier is passive (other than its normal operations), whilst the gatherer actively seeks out the information to be presented.

The first stage of enumeration (determining what suppliers are present) is performed with a service call, and the second stage (determining what statistics are available and their values) is performed through a SWI whose SWI number is obtained during the first stage of enumeration. This SWI number is used for all stages of operation apart from enumeration itself.

Each statistic has a number of different pieces of information associated with it, forming its description, and a value. The description provides the necessary information to access and manipulate the value, including the number of bytes of storage required for the value, its type, format and desired presentation. The data types supported are boolean, integer and string. An unused data type also provides for padding.

Descriptions and statistics are read in ranges from a lower statistic number to an upper statistic number, inclusive. The first statistic of any supplier is zero. The highest statistic number of a supplier is obtained when the SWI number for a supplier is obtained. A range is always processed atomically by the supplier, ensuring consistent values and presentation to a gatherer when so required. A supplier indicates the volatility of its statistics and typically attempts to group statistics into ranges of the same volatility.

Enumerating suppliers

The suppliers are enumerated with Service_StatisticEnumerate. Each supplier allocates a small structure from the RMA, initialises it and links it into the linked list whose head is pointed to by R0. Whether the supplier adds an entry at the head or tail of the list does not matter. If a gatherer requires any specific order, then it should explicitly sort the suppliers list itself. A gatherer should not cache SWI values across invocations of suppliers, as a module might choose a dynamic SWI numbering scheme if it offers multiple effective suppliers.

In C, the structure is defined as follows:

typedef struct spctl

{

  struct spctl    *next;         /* Next structure in list */

  unsigned int     i_version;    /* Interface version */

  unsigned long    features;     /* Combination of SF_ values */

  unsigned int     swinumber;    /* The SWI SA_DESCRIBE/SA_READ use */

  unsigned int     max_stat;     /* Highest stat number (inclusive) */

  unsigned int     type;         /* Acorn assigned supplier type */

  unsigned int     s_version;    /* Supplier version */

  char            *module;       /* Module name (short one) */

  char            *title;        /* Title string - short */

  char            *description;  /* Descriptive string - long */

  unsigned char    reset[8];     /* Unique for each invocation */

} dci4_spctl;

and its fields are:

The supplier types currently defined are (expressed in C):

#define SPT_GENERAL_SUPPLIER 0  /* Use this if no other suitable type */

#define SPT_NETWORK_PROTOCOL 1  /* A DCI4 protocol module */

#define SPT_NETWORK_DRIVER   2  /* A DCI4 device driver module */

#define SPT_MBUF_MANAGER     3  /* The DCI4 mbuf manager module */

When a gatherer has finished interacting with a supplier, it should free the allocated structure back into the RMA.

Communicating with a supplier

Apart from the enumeration phase, all communication with a supplier is performed through the single SWI number obtained during the enumeration phase. The action performed by this "statistic SWI" is controlled by R0 on entry, which contains an action code. The defined action codes are:

SA_DESCRIBE      0

SA_READ          1

SA_DESCRIBE obtains descriptions of statistics, whilst SA_READ obtains the actual values of statistics. It is necessary to first obtain the description of a statistic before reading it, as the description is the only way the gatherer can obtain the size of the statistic value and know how much buffer space to allocate.

The register usage for both SA_DESCRIBE and SA_READ is very similar. In essence, both these actions enumerate information about a range of statistics into the buffer supplied. This is performed atomically, where necessary, by the supplier. In both cases, the operation starts from the first statistic and proceeds in steps of one and stops once the last statistic has been processed. Output is placed into the buffer supplied. If this buffer is not big enough for the requested range of statistics, then processing will stop when it is no longer possible to write all the necessary information for a statistic (ie if the buffer supplied is not big enough, the number of unused bytes will be less than the size of a statistic description). Return values of the number of statistics processed and the number of bytes of the buffer used are returned. The buffer must be word aligned in memory.

Statistic descriptions

Each statistic is described with a fixed sized buffer, described in C as follows:

typedef struct stdesc

{

  int           type;          /* ST_ series */

  unsigned int  format;        /* SxF_ series */

  unsigned int  presentation;  /* SxP_ series */

  unsigned int  size;          /* Measured in bytes */

  unsigned int  volatility;    /* SV_ series */

  char         *name;          /* String is static */

  unsigned int  name_tag;      /* See specification */

  unsigned int  spare;         /* Unused. Always zero */

} dci4_stdesc;

and its fields are:

The possible values of the type field are:

#define ST_UNUSED           0

#define ST_BOOLEAN          1

#define ST_STRING           2

#define ST_INTEGER8         3

#define ST_INTEGER16        4

#define ST_INTEGER32        5

#define ST_INTEGER64        6

#define ST_ADDRESS          7

#define ST_TIME             8

The three possible values of the volatility field are:

#define SV_STATIC           0       /* Constant per invocation */

#define SV_VARIABLE         1       /* Unlikely to have changed in 5 minutes */

#define SV_VOLATILE         2       /* Can change very rapidly */

Statistic types

Ping pong atomicity

The supplier is required to perform each read request atomically. This means a gatherer can rely upon a read operation producing consistent statistics, but it cannot be certain quite when in time these statistics apply to; in some cases, statistics are virtually always out of date by the time the gatherer obtains and uses them.

The simplistic approach to ensuring an atomic read operation is to perform the entire action with interrupts disabled. This, however, has an undesirable effect on interrupt latency for suppliers with many or complex statistics and is not recommended.

The suggested method is a three buffer scheme. One buffer holds the accumulated statistics, the second holds the increments (deltas) being generated "live", and the third is either entirely full of zero values, or there is an active read operation in progress and it holds a previous set of increments that are currently being added (merged) into the accumulated values.

Two pointers are maintained. One for the "live" buffer and the other for the "merge" buffer. The operation that is necessary to perform atomically is the swapping of these two pointer values.

The overall structure suggested is as follows:

start thread of control (ie SWI)

    enter mutex (eg disable interrupts)

        temp := buffer pointer 1

        buffer pointer 1 := buffer pointer 2

        buffer pointer 2 := temp

    exit mutex (and ensure interrupts enabled)

    add values from buffer pointer 2 into the accumulated values

    zero the memory described by buffer pointer 2

end thread of control (ie SWI)

This maximises the usefulness of the non re-entrancy requirement and requires ONLY the swapping of the buffer pointers to be performed atomically. All other operations can proceed with interrupts enabled. This minimal critical region is the prime motivation behind this scheme.

Additional notes

Some applications of the statistic interface will require a single RISC OS module to behave as multiple suppliers. For example, a device driver module that controls multiple interfaces might well wish to provide an overall set of statistics, and then an instance of a set of statistics per interface controlled. A separate SWI number is required for each 'effective supplier'. This is not normally a problem, as very few modules approach the limit of the 64 separate SWIs allocated. Gatherers are expected to obtain SWI numbers through the enumeration method supplied, and should be capable of handling dynamic SWI number assignment. For example, a device driver may choose SWIs 63, 62 and 61 for units 0, 1 and 2, respectively. If a gatherer were to attempt to 'cache' these SWI numbers across invocations of the device driver, then it might not correctly cater for the addition or removal of interfaces.