ChorusOS man pages section 2DL: Data Link Services

svDataLink(2DL)

NAME

svDataLink, svDataLinkAttach, svOutFrameFree, svInputFrameDeliver- Attach a ChorusOS IPC Data Link Driver; Free an outgoing frame; Deliver an incoming frame

SYNOPSIS

#include <ipc/extDtLink.h>

dtLink

outFrame

dtLink

inputFr

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

IPC_REMOTE

DESCRIPTION

ChorusOS includes an implementation of remote ChorusOS IPC over network media (termed Data Links in the ChorusOS IPC terminology). The system calls described below allow the driver of a data link to implement the transmission of ChorusOS IPC messages over it. The driver must be part of of a supervisor actor which declares itself to the ChorusOS microkernel using the svDataLinkAttach() system call.

The function of a data link driver is to transmit ChorusOS IPC frames between ChorusOS sites, in both unicast and broadcast modes. The maximum frame size is defined by the data link driver, according to the characteristics of the underlying network medium. The only transmission guarantee expected from the data link driver is frame integrity: the data link driver must insure that the frame contents are preserved during transmission. In addition, to ensure proper ChorusOS IPC performance, the data link driver should transmit every frame and maintain a FIFO ordering. Disordered or lost frames are tolerated by IPC protocols, but should be avoided.

PARAMETERS

A Data Link driver registers itself through the svDataLinkAttach() system call, providing a pointer to a structure of type ExtDtLink as pictured below:

typedef enum {
    DTLINK_VERSION_INITIAL = 0      /* initial version */
} DtLinkVersion;

typedef struct {
    DtLinkVersion version;          /* data link driver version */
    void*         cookie;           /* Reserved for use by microkernel */
    char*         dtLinkName;       /* Data link driver name */
    uint32_f      frameHdrSize;     /* e.g. 14 for Ethernet */
    uint32_f      outFrameMaxSize;  /* must include frameHdrSize */
    uint32_f      inFrameHdrSize;   /* <= frameHdrSize */
    uint32_f      throughput;       /* in bits per second */
    OutFrameSend  frameSend;        /* to a particular remote site */
    OutFrameSend  frameBcast;       /* to all reachable sites */
} ExtDtLink;

The field version must contain the version number of the interface supported by the external data link driver. The version number is incremented each time the ExtDtLink structure is extended in order to include new services. In other words, a new symbol is added to the DtLinkVersion enum (for example, DTLINK_VERSION_1 = 1 ) each time such an API extension is done.

The field cookie is reserved to the microkernel.

The field dtLinkName is a pointer to a character string which contains the name of the Data Link device.

The field frameHdrSize is the size of the data link header which is appended by the data link driver to each output frame. For instance, on Ethernet, this size is equal to 14 bytes. This information will allow the microkernel to allocate room for the data link header within each output frame.

The field outFrameMaxSize is the maximum frame size, including frameHdrSize , of the underlying physical network medium.

The field inFrameHdrSize is the size of the data link header within IPC input frames provided by the driver to the microkernel. This information is useful for drivers which must skip part or all of the data link header embedded within input frames before providing them to the microkernel through the svInputFrameDeliver() system call described below.

The field throughput is the throughtput in bit per second of the underlying network medium.

The fields frameSend and frameBcast contain the address of the functions which are exported by the driver to the microkernel to transmit output IPC frames over the data link network medium. Both functions are invoked with two arguments:

A pointer to a structure of type CnOutFrame as described below.
A pointer to the ExtDataLink structure associated to the underlying data link device.

The CnOutFrame structure describes the frame to send as follows:

typedef struct {
    NetFrame netFrame;
    uint32_f destSite;
    uint16_f msgFlags;
} CnOutFrame;

The field netFrame is a structure of type NetFrame which describes the frame data to be sent, as defined in the file <ddi/net/netFrame.h> :

typedef struct NetFrame* NetFramePtr;
typedef void (*NetFrameFree)(NetFramePtr);

typedef struct NetFrame {
    struct NetFrame* next;
    uint32_f         frameSize;
    NetBuf*          bufList;
    NetFrameFree     freeFrame;
} NetFrame;

The field next allows drivers to insert output frames into a list of pending frames, whenever device transmit resources are exhausted.

The field bufList is the head of a single-linked list of NetBuf structures which describe the memory buffer or buffers holding the frame data to be transmitted. Each NetBuf structure in the list is composed as follows:

typedef struct NetBuf {
    struct NetBuf* next;
    uint32_f       bufSize;
    char*          bufAddr;
} NetBuf;

where:

next points to the next NetBuf structure in the list and is equal to 0 (ZERO) in the last buffer.
bufSize is the size of the data memory buffer.
bufAddr is the beginning of the data memory buffer.

The field frameSize is the total size of the frame to transmit. The value of frameSize is granted to be lower or equal than the value of the field outFrameMaxSize of the ExtDtLink structure. The space for storing the Data Link header of size frameHdrSize has already been reserved by the microkernel at the beginning of the first memory buffer of the frame. This means that the data link driver must store the appropriate data link header at the beginning of the first memory buffer. Accordingly, the bufSize field of the first memory buffer and the frameSize field of the netFrame structure embedded within the CnOutFrame structure already includes the size of the data link frame header.

The field freeFrame is the address of the function which must be invoked by the driver to free the frame once it has been transmitted over the network.

The field destSite of the CnOutFrame structure identifies the destination site or sites to which the frame must be sent. When provided to the frameSend() function, the field destSite contains the ChorusOS site number of the destination site of the frame. When provided to the frameBcast() function, the field destSite is set to 0xFFFFFFFF . This allows data link drivers to have a single frameSend() function which dynamically test the field frameDest in order to distinguish between unicast and broadcast frames.

The field msgFlags describes the priority of the output frame. When set to the CN_URGENT_MSG constant, the driver should try to transmit the outframe as quickly as possible.

EXTENDED DESCRIPTION

Once an output frame has been sent, the data link driver must invoke the freeFrame() function which is embedded within the NetFrame structure of the output frame. For this purpose, the following shortcut macro is provided:

   svOutFrameFree(CnOutFrame* outFrame)

The freeFrame() function can be invoked from an interrupt handler, as end of transmission events are usually notified through interrupts by network devices.

When receiving a frame from the network, the data link driver must invoke the svInputFrameDeliver() system call with two arguments:

The address of the ExtDtLink structure which was provided to the svDataLinkAttach() system call.
A pointer to structure of type NetFrame which describes the received frame.

The svInputFrameDeliver() system call is intended to be invoked from an interrupt handler. Upon return from svInputFrameDeliver() , the frame data described within the NetFrame structure has been copied by the microkernel and the data link driver can reuse it (for example, put it back into the receive ring of the network controller).

RETURN VALUES

The svDataLinkAttach function returns a value of 0 when successfully completed. Otherwise, a negative error code is returned.

ERRORS

K_EINVAL: A data link driver has already declared itself.
K_ENOMEM: The microkernel is out of resources.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

ChorusOS 5.0 Last Revised December 2001