ChorusOS man pages section 2DL: Data Link Services

svInputFrameDeliver(2DL)

NAME

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

SYNOPSIS

#include <ipc/extDtLink.h>

dtLink

outFrame

dtLink

inputFr

FEATURES

IPC_REMOTE

DESCRIPTION

ChorusOS includes an implementation of remote Chorus IPC over Ethernet (through the DATALINK_INET feature, when combined with ETHERNET). The system calls described below allow users to implement the transmission of Chorus IPC messages over other network types. To implement Chorus IPC over a new network medium, perform the following steps:

Unset any DATALINK_ features from the system configuration.
Load a supervisor actor which declares itself to the ChorusOS kernel using the svDataLinkAttach system call. This actor is called a data link driver .

The primary function of a data link driver is to transmit Chorus IPC message frames between Chorus sites, in both unicast and broadcast modes. The maximum frame size is defined by the data link driver, rather than being imposed by the ChorusOS kernel. 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 Chorus 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.

svDataLinkAttach function registers a new data link driver. The dtLink parameter is a pointer to an ExtDtLink structure whose members are the following:

typedef struct ExtDtLink_t {
     void*         cookie;         /* Reserved - only used by the kernel */
     char*         dtLinkName;     /* Data link driver name */
     unsigned int  frameHdrSize;   /* e.g. 14 for Ethernet */
     unsigned int  maxFrameSize;   /* Must include frameHdrSize */
     FrameSend     frameSend;      /* To a particular remote site */
     FrameSend     frameBcast;     /* To all reachable sites */
} ExtDtLink;

The data link driver sends the following information to the ChorusOS kernel:

The name of the data link driver as a character string, pointed to by dtLinkName .
The size of its frame header,expressed in bytes in frameHdrSize; this information will allow the kernel to allocate room for the data link header within each frame.
The maximum frame size (including the frame header), expressed in bytes in maxframeSize
The function which the kernel will invoke when sending a unicast frame, in frameSend .
The function which the kernel will invoke when sending a broadcast frame, in frameBcast .

Both frameSend and frameBcast are pointers to functions whose arguments are the following:

void frameSend (
     CnOutFrame*   frame,
     ExtDtLink*    dtLink);

The dtLink parameter is a pointer to the ExtDtLink structure declared by the data link driver when it attaches itself. The frame parameter is a pointer to a CnOutFrame structure, which describes the frame to be sent, as follows:

typedef struct CnOutFrame_t {
     struct CnOutFrame_t*   next;
     unsigned int           totalLength;
     MemBuffer*             bufList;
     unsigned int           destSite;
} CnOutFrame;

The destSite parameter identifies the Chorus site number to the frameSend function. When sent to the frameBcast function, destSite is set to 0xFFFFFFFF. This allows data link drivers to implement a single function, and to check for broadcast mode from the destination site number.

The bufList parameter is the first of a single-linked list of MemBuffer structures which describe the memory buffers holding the frame data, as follows:

typedef struct MemBuffer_t {
     struct MemBuffer_t*   next;
     char*                 address;
     unsigned int          size;
} MemBuffer;

The next pointer indicates the next MemBuffer on the list, and is NULL in the last buffer. The address pointer indicates the first byte of the memory buffer, and size is the size of the memory buffer, expressed in bytes.

The total frame size is given by totalLength, and is assumed to be lower than or equal to the maxFrameSize field of dtLink.

When a frame is passed to the data link driver, the space for storing the data link header has been reserved at the beginning of the first memory buffer. The size field of the first memory buffer, as well as the totalLength field of the frame descriptor both include the size of the data link header.

When the data link driver is invoked to send a frame, it should perform the following functions:

Resolve the address(es) of the destination node(s) from the Chorus site number ( destSite ).
Update its header within the frame.
Send or broadcast the frame.

The frameSend function may be invoked from an interrupt (time-out handler) by the kernel.

When a frame has been sent, the data link driver must invoke svOutFrameFree in order to notify the kernel that the frame data can be freed.

When receiving a frame from the network, the data link driver must invoke the svInputFrameDeliver system call. The dtLink parameter is a pointer to the data link descriptor, inputFr is a pointer to the CnInFrame structure, which describes the frame received, as follows:

typedef struct CnInFrame_t {
     struct CnInFrame_t*   next;
     unsigned int          totalLength;
     MemBuffer*            bufList;
} CnInFrame;

The next , totalLength and bufList have the same meanings as in the CnOutFrame structure.

The svInputFrameDeliver function is intended to be invoked from an interrupt. Upon return from svInputFrameDeliver, the data described by inputFr has been copied by the kernel into receiver memory, and the data link driver can reuse it (for example, put it back into a network controller receive ring).

RETURN VALUE

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 system is out of resources.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

ChorusOS 4.0 Last Revised December 1999