DCI 4 networkingNetwork Device Drivers

Backwards compatabilty

The radical changes and new features being introduced with this new version of the DCI, along with the inbuilt lack of flexibility in previous versions, combine to make any attempt at backwards compatibility impossible. With this lack of compatibility, care has been taken to ensure that there is no overlap between DCI 4 compliant modules, and other modules loaded on the same machine that implement earlier versions of the DCI, specifically:

1. In both old and new DCI versions, it is the responsibility of the protocol module to initialise the interface between itself and a device driver after either actively or passively learning of the device driver's presence; DCI 4 has replaced the active (Service_FindNetworkDriver) and passive (Service_NetworkDriverStatus) service calls used by protocol modules with Service_EnumerateNetworkDrivers and Service_DCIDriverStatus respectively.
2. To prevent old device drivers getting confused by Service_ProtocolStatus, which no longer provides a sensible (as far as old DCI versions are concerned) value in R2, this service call has been made obsolete, and has been replaced by Service_DCIProtocolStatus.

Identifying Device Drivers

Device drivers are always identified by their "Driver Information Block", described on page 4. These Driver Information Blocks are used in a number of service calls, and are also given to protocol modules along with received frames.

There are fields within a Driver Information Block which uniquely identify each interface, but to prevent protocol modules having to make laborious (i.e. strcmp()) comparisons of these fields, device drivers should maintain a single, static, Driver Information Block for each interface it controls. In this way, protocol modules need only compare the address of Driver Information Blocks to identify an interface.

This scheme means that any use of the *RMTidy RISC OS command will kill any network stack on the machine --- this is not a great problem, since anyone who uses rmtidy in a modern RISC OS system is asking for all the trouble that they are about to receive. However, if a device driver module is re-initialised (via rmreinit), then the address of its Driver Information Block will change, therefore any protocol module's handler for the Service_DCIDriverStatus service call (page 6) cannot compare addresses, but must fall back to comparing those fields which uniquely identify an interface, i.e. dib_name & dib_unit.

Driver Information Blocks

Device drivers identify themselves via a Driver Information Block, which can be expressed in C syntax as

struct dib
{
    unsigned int dib_swibase;
    char *dib_name;
    unsigned int dib_unit;
    unsigned char *dib_address;
    char *dib_module;
    char *dib_location;
    struct slot dib_slot;
    unsigned int dib_inquire;
};

The fields within this structure are:

Note that there is a subtle, but important, distinction between this definition of a Driver Information Block and its definition in previous versions of the DCI: the new definition has one Driver Information Block per unit, rather than one per device driver; if a device driver controls several units, then it must provide one struct dib per unit.

Units: a single device driver may control more than one physical network interface, either by driving multiple network cards, or by driving multiple interfaces on a single card. The driver is responsible for allocating a number to each interface under its control --- the first interface being unit 0, the second interface being unit 1, and so on. Any particular network connection can then be uniquely identified by its driver name and unit number, e.g. en0, ea2. If an interface is found to be faulty during any hardware check its driver may perform, the interface must still be assigned a unit number, and must still appear in the enumerated list of device drivers.

Chained Driver Information blocks

The results from the Service_EnumerateNetworkDrivers service call are chained together into a linked list of Driver Information Blocks. The C structure used for this linked list is

struct chaindib
{
    struct chaindib *chd_next;
    struct dib *chd_dib;
};

Just in case the fields within this structure are not self-evident, they are:

Protocol Information Blocks

In much the same way that device drivers are identified by their Driver Information Block, older versions of the DCI used to contain a Protocol Information Block which identified individual protocol modules. This Protocol Information Block is not needed in DCI 4, and has been removed.

Standardised Errors

In an attempt to force some consistency, this sub-section defines some of the errors which various SWIs, and the circumstances in which these errors may be returned. This is not meant to be an exhaustive list, merely to cover all the errors explicitly mentioned in this document, plus some other common faults.

• Any SWI:

  Error number	Unix error	Meaning
  &20E16	EINVAL	Incorrect flags word in R0
  &20E06	ENXIO	Invalid unit number supplied

• SWI DCIDriver_SetNetworkMTU:

  Error number	Unix error	Meaning
  &20E19	ENOTTY	Illegal op for device

• SWI DCIDriver_Transmit:

  Error number	Unix error	Meaning
  &20E86		Transmission is blocked
  &20E32	ENETDOWN	Network hardware is down.
  &20E28	EMSGSIZE	Frame length > network MTU.
  &20E37	ENOBUFS	Not enough mbufs available.

• SWI DCIDriver_Filter:

  Error number	Unix error	Meaning
  &20E87		Frame type already claimed
  &20E16	EINVAL	Trying to claim illegal frame type
  &20E16	EINVAL	Trying to release a non-existent claim.
  &20E01	EPERM	Trying to free another protocol's claim.

• SWI DCIDriver_MulticastRequest:

  Error number	Unix error	Meaning
  &20E16	EINVAL	Trying to claim illegal frame type
  &20E16	EINVAL	Trying to release a non-existent claim.

Deleted SWI Details

As mentioned above, some of the SWIs from earlier versions of the DCI have been removed from DCI 4. These SWIs are:

Frame Type

DCI 4 splits the 32-bit frame type into two 16-bit subfields --- the hi-order 16 bits specify the frame class and level, while the lo-order 16 bits provide the exact frame type (where significant).

Expressed in C format, the class/level subfield can take the following values:

#define FRMLVL_E2SPECIFIC 0x0001
#define FRMLVL_E2SINK 0x0002
#define FRMLVL_E2MONITOR 0x0003
#define FRMLVL_IEEE 0x0004

All other values for this subfield are illegal --- any attempt to use them in a SWI DCIDriver_Filter SWI should generate an error; similarly, if the hi-order subfield of the frame type is FRMLVL_E2SPECIFIC, then the lo-order subfield can take any value from 0x0000 -- 0xffff, otherwise it must be set to 0x0000, and any other value passed to Filter should be treated as an error.

The precise meanings of the class/level subfield values are:

For Ethernet 2.0 frames, the table below gives a summary of what frame levels are allowed on new claims, given the highest level of filtering currently active (monitor is considered higher than sink, and both of these levels are considered higher than normal)

Address Level

The four levels of address level filtering can be expressed in C as

#define ADDRLVL_SPECIFIC 0
#define ADDRLVL_NORMAL 1
#define ADDRLVL_MULTICAST 2
#define ADDRLVL_PROMISCUOUS 3

These levels are:

Most Ethernet controllers can perform this address filtering at a hardware level, but, obviously, the hardware needs to be configured to the loosest level of filtering requested by any protocol module. In the situation where two protocol modules have specified two different levels of address filtering, the device driver must still filter out unwanted frames; protocol modules are only responsible for filtering out any unwanted subset of multicast frames.

Error Level

A device driver should provide two levels of error filtering, in C these are

#define ERRLVL_NO_ERRORS 0
#define ERRLVL_ERRORS 1

These levels are:

Handler Details

On entry:

R0 = pointer to Driver Information Block describing the source interface

R1 = pointer to head of mbuf list of received frames

R12 = protocol module's private word pointer, i.e. value passed in R5 to SWI DCIDriver_Filter SWI

On exit:

All registers preserved.

Interrupt Status: Both interrupts and fast interrupts are enabled by the received frame handler.

Details of the exact structure of the mbuf list of received frames are given in the section below.

Each received frame has a header which can be described in terms of the following C structure:

struct rx_hdr
{
    void *rx_ptr;
    unsigned int rx_tag;
    unsigned char rx_src_addr[6], _spad[2];
    unsigned char rx_dst_addr[6], _dpad[2];
    unsigned int rx_frame_type;
    unsigned int rx_error_level;
    unsigned int rx_cksum;
}

The fields in this structure are:

This frame header is passed in the first mbuf of each frame, the first byte of the frame data is in the second mbuf in the chain.

Note that DCI versions before 4.05 did not have the rx_cksum field; similarly later versions may have extra fields. Hence protocol modules must not fault unexpectedly long header mbufs; nor should they fault short headers, unless they were relying on the extra fields.

Mbuf Chaining

An mbuf contains two fields which point to the next mbuf in a linked list, specifically

When a device driver calls a protocol module's receive handler, it uses a single mbuf chain to hold each received frame, and can link several frames together for passing via the single call. Figure 2 shows how m_next and m_list are used to link chains of mbufs together into a list.

Note that, although this structure allows different frame types to be passed to the protocol module (because the first mbuf+ in each chain contains a struct rx_hdr which includes the frame_type field), the receive handler is only given a single Driver Information Block, and therefore all the frames passed in any one call to the handler must come from a single unit.

Overview

Memory management for packet storage in earlier versions of the DCI is performed with mbufs. DCI 4 also uses mbuf based packet storage, but there are some differences. These differences are for the following reasons:

1. Correct design oversights in previous versions of the DCI.
2. Provide a more modular, and upgradeable, system.
3. Offer single mbuf arbiter with optimised routines available to all DCI4 components.

The memory manager, the arbiter module, is central to the DCI4 mbuf scheme. It performs most of the low level work associated with mbufs, as well as relieving both protocol and client modules of some tedium.

A complete specification of the memory manager is available separately; this document is designed to guide the reader conversant with "traditional" mbufs through using DCI4 mbufs.

Communication with the memory manager is centred around an mbctl structure. This is stored in the client's memory, and is mainly initialised by the memory manager to contain useful information, including the addresses of a number of routines within the memory manager for the client to call directly.

Direct entry points are designed to permit the easy inter-operation of assembler and APCS code (such as that generated by the NorCroft C compiler), and roughly obey APCS. A list of entry/exit characteristics follows (using APCS register naming convention):

1. a1 always points at an mbctl structure for all direct entry calls
2. the processor must be in supervisor mode
3. a1--a4 are the only parameter registers
4. a2--a4 and ip are corrupted by the call
5. a1 is either the call result or corrupted
6. other registers preserved by call
7. the processor flags are preserved by the call
8. no V set error convention (incompatible with APCS)
9. in general, an error results in a1=0 on exit
10. IRQ state preserved across call
11. IRQs may be disabled during calls
12. IRQs may be enabled during calls ONLY if specifically documented
13. FIQs assumed enabled on entry
14. FIQs preserved across calls

Currently, no direct entry point routine will enable interrupts if they are disabled on entry.

The header file mbuf.h provides some macros to manage interfacing with the memory manager routines.

These direct entry points provide access to allocator and free routines, along with a whole host of support routines. Rather than each protocol implementing it's own mbuf scheme, and each device driver having to choose the correct mbuf pool to allocate from, all protocols and all device drivers perform their allocations and frees via these direct entry points.

Structures

The new memory manager module uses two main data structures: the mbuf structure, each one of which describes a piece of atomically allocated memory, and struct mbctl, the control struture which describes the exact interface between the memory manager and one of its clients.

Note that, although a struct mbuf is recognisably similar to the structure used in "traditional" memory management schemes, there are enough differences in the new structure to render it incompatible with the macros defined in the traditional versions of mbuf.h.

The new definition of an mbuf is shown below:

typedef struct mbuf
{
    struct mbuf *m_next; /* next mbuf in chain */
    struct mbuf *m_list; /* next mbuf in list (clients only) */
    ptrdiff_t m_off; /* current offset to data from mbuf itself */
    size_t m_len; /* current byte count */
    const ptrdiff_t m_inioff; /* original offset to data from mbuf itself */
    const size_t m_inilen; /* original byte count (for underlying data) */
    unsigned char m_type; /* client use only */
    const unsigned char m_sys1; /* MBufManager use only */
    const unsigned char m_sys2; /* MBufManager use only */
    unsigned char m_flags /* client use only */
    struct pkthdr m_pkthdr; /* client use only */
} dci4_mbuf;

The MLEN macro value is no longer directly applicable --- each mbuf must have its maximum size checked individually. Likewise, reseting m_off now requires examining the m_inioff field of the mbuf - just setting it to zero is no longer good enough.

m_act has been renamed m_list.

m_inilen and m_inioff are provided to replace the MMINOFF and MMAXLEN macros, as the values are now dependent upon the particular mbuf in question.

m_indir has disappeared --- specific routines exist for determining if an mbuf chain contains unsafe data.

The mbuf structure has been separated from the underlying storage it describes. The underlying storage blocks may now be different sizes (128 and 1536 byte blocks are currently used).

Earlier versions of the DCI had big mbufs, but they were weakly defined and dtom did not work with them. DCI 4 corrects both these points --- indirect mbufs, which at times were not distinguishable from large mbufs, have been formalised into unsafe mbufs.

As an mbuf chain passes around the system, ownership of that chain is also transferred. Ownership brings with it the responsibility to free the mbuf chain (unless it is transferred to another component, although this is unlikely).

The other crucial structure in DCI 4 memory management is mbctl:

typedef struct mbctl
{
    /* reserved for MBufManager use in establishing context */
    int opaque; /* MBufManager use only */

    /* Client initialises before session is established */
    size_t mbcsize; /* size of mbctl structure from client */
    unsigned int mbcvers; /* client version of MBufManager* spec */
    unsigned long flags; /* */
    size_t advminubs; /* Advisory desired minimum underlying block size */
    size_t advmaxubs; /* Advisory desired maximum underlying block size */
    size_t mincontig; /* client required min ensure_contig value */
    unsigned long spare1; /* Must be set to zero on initialisation */

    /* MBufManager initialises during session establishment */
    size_t minubs; /* Minimum underlying block size */
    size_t maxubs; /* Maximum underlying block size */
    size_t maxcontig; /* Maximum contiguify block size */
    unsigned long spare2; /* Reserved for future use */

    /* Allocation routines */
    struct mbuf * /* MBC_DEFAULT */
    (* alloc)
    (struct mbctl *, size_t bytes, void *ptr);

    struct mbuf * /* Parameter driven */
    (* alloc_g)
    (struct mbctl *, size_t bytes, void *ptr, unsigned long flags);

    struct mbuf * /* MBC_UNSAFE */
    (* alloc_u)
    (struct mbctl *, size_t bytes, void *ptr);

    struct mbuf * /* MBC_SINGLE */
    (* alloc_s)
    (struct mbctl *, size_t bytes, void *ptr);

    struct mbuf * /* MBC_CLEAR */
    (* alloc_c)
    (struct mbctl *, size_t bytes, void *ptr);

    /* Ensuring routines */
    struct mbuf *
    (* ensure_safe)
    (struct mbctl *, struct mbuf *mp);

    struct mbuf *
    (* ensure_contig)
    (struct mbctl *, struct mbuf *mp, size_t bytes);

    /* Freeing routines */
    void
    (* free)
    (struct mbctl *, struct mbuf *mp);

    void
    (* freem)
    (struct mbctl *, struct mbuf *mp);

    void
    (* dtom_free)
    (struct mbctl *, struct mbuf *mp);

    void
    (* dtom_freem)
    (struct mbctl *, struct mbuf *mp);

    /* Support routines */
    struct mbuf * /* No ownership transfer though */
    (* dtom)
    (struct mbctl *, void *ptr);

    int /* Client retains mp ownership */
    (* any_unsafe)
    (struct mbctl *, struct mbuf *mp);

    int /* Client retains mp ownership */
    (* this_unsafe)
    (struct mbctl *, struct mbuf *mp);

    size_t /* Client retains mp ownership */
    (* count_bytes)
    (struct mbctl *, struct mbuf *mp);

    struct mbuf * /* Client retains old, new ownership */
    (* cat)
    (struct mbctl *, struct mbuf *old, struct mbuf *new);

    struct mbuf * /* Client retains mp ownership */
    (* trim)
    (struct mbctl *, struct mbuf *mp, int bytes, void *ptr);

    struct mbuf * /* Client retains mp ownership */
    (* copy)
    (struct mbctl *, struct mbuf *mp, size_t off, size_t len);

    struct mbuf * /* Client retains mp ownership */
    (* copy_p)
    (struct mbctl *, struct mbuf *mp, size_t off, size_t len);

    struct mbuf * /* Client retains mp ownership */
    (* copy_u)
    (struct mbctl *, struct mbuf *mp, size_t off, size_t len);

    struct mbuf * /* Client retains mp ownership */
    (* import)
    (struct mbctl *, struct mbuf *mp, size_t bytes, void *ptr);

    struct mbuf * /* Client retains mp ownership */
    (* export)
    (struct mbctl *, struct mbuf *mp, size_t bytes, void *ptr);
} dci4_mbctl;

Some of the fields the client initialises are present to permit future versions of the memory manager to tune themselves as tightly as possible to the setup they are asked to support.

Note that dtom is no longer a macro. Don't worry --- it's efficient assembler, and it works with all sizes of mbuf the memory manager cares to use.

Using the memory manager module

Basic use of the memory manager is performed as follows

1. module loads and looks for memory manager
2. if memory manager is absent, module goes into a pre-active state, awaiting the arrival of the memory manager
3. once the memory manager is present, a "session" is opened with it
4. the device driver/protocol may now become active if it is pre-active (this might involve delaying arrival service calls until now)
5. the device driver/protocol uses direct entry points to communicate with the memory manager
6. the device driver/protocol is about to die --- it first closes the open session with the memory manager
7. the device driver/protocol can now die

Initialisation with the memory manager is performed with code something like:

static _kernel_oserror *open_mbuf_manager_session(void)
{
    _kernel_swi_regs r;
    memset(&mbctl, 0, sizeof(struct mbctl));
    mbctl.mbcsize = sizeof(struct mbctl);
    mbctl.mbcvers = MBUF_MANAGER_VERSION;
    mbctl.flags = 0;
    mbctl.advminubs = 0;
    mbctl.advmaxubs = 0;
    mbctl.mincontig = 0;
    mbctl.spare1 = 0;
    r.r[0] = (int) &mbctl;
    return(_kernel_swi(Mbuf_OpenSession, &r, &r));
}

Finalisation is performed with code something like:

static _kernel_oserror *close_mbuf_manager_session(void)
{
    _kernel_swi_regs r;
    r.r[0] = (int) &mbctl;
    return(_kernel_swi(Mbuf_CloseSession, &r, &r));
}

A quick summary of the available direct entry point routines:

So, a device driver might use the allocator as follows:

struct mbuf *mp = mbctl.alloc(&mbctl, packlen, NULL);

which allocates an mbuf chain of "packlen" bytes.

The entire chain might later be freed thus:

mbctl.freem(&mbctl, mp);

The reason all the direct entry point calls take a (struct mbctl *) value as there first parameter is to permit the MBufManager to establish a context within which it is operating (ie find its workspace!).

Finally, the memory manager supports the DCI4 statistics interface. This can be useful in fine tuning your DCI4 component.