muxTkLib

NAME

muxTkLib - MUX toolkit Network Interface Library

ROUTINES

muxTkDrvCheck( ) - checks if the device is a NPT or END interface
muxTkBind( ) - bind an NPT protocol to a driver
muxTkReceive( ) - Receive a packet from a NPT driver.
muxTkSend( ) - send a packet out on a Toolkit or END network interface
muxTkPollSend( ) - send a packet out in polled mode to an END or NPT interface
muxTkPollReceive( ) - poll for a packet from a NPT or END driver

DESCRIPTION

This library provides additional APIs offered by the Network Protocol Toolkit(NPT) architecture. These APIs are an extension to the original release of the MUX interface.
A NPT driver is an enhancement to an END but retains all of the END's functionality. NPT also introduces the term "network service sublayer" or simply "service sublayer" which is the component that interfaces the network service(network protocol) and the MUX.

INCLUDE FILES

errno.h, lstlib.h, logLib.h, string.h, m2Lib.h, bufLib.h, if.h, end.h, muxLib.h, muxTkLib.h

muxTkDrvCheck( )

NAME

muxTkDrvCheck( ) - checks if the device is a NPT or END interface

SYNOPSIS

int muxTkDrvCheck
    (
    char * pDevName
    )

DESCRIPTION

This function returns 1 in the case of Toolkit(NPT) driver and 0(zero) for an END. This routine would be called by the network service sublayer to find the driver type before it binds to it via the MUX.

RETURNS

1 for NPT driver, 0 for END or other driver, or ERROR(-1) if the device is not found

muxTkBind( )

NAME

muxTkBind( ) - bind an NPT protocol to a driver

SYNOPSIS

void * muxTkBind
    (
    char *                      pName, /* interface name, for example, ln, */
    int                         unit,  /* unit number */
    BOOL (* stackRcvRtn) (void* 
    )

DESCRIPTION

A Network Protocol Service sublayer uses this routine to bind to a specific NPT driver. This bind routine is valid for both END and NPT drivers, but the specified stack receive routine must use the NPT function prototype.
The driver is specified by the pName and unit arguments, (for example, ln and 0, ln and 1, or ei and 0).
The stackRcvRtn is called whenever the MUX has a packet of the specified type. If the type is MUX_PROTO_PROMISC, the protocol is considered promiscuous and will get all of the packets that have not been consumed by any other protocol. If the type is MUX_PROTO_SNARF, it will get all of the packets that the MUX sees.

pName
Expects a pointer to a character string that contains the name of the device that this network service wants to use to send and receive packets.

unit
Expects the unit number of the device of the type indicated by pName.

stackRcvRtn
Expects a pointer to the function that the MUX will call when it wants to pass a packet up to the network service. For a description of how to write this routine, see the section Receiving Packets, NPT Users Guide"

stackShutdownRtn
Expects a pointer to the function that the MUX will call to shutdown the network service. For a description of how to write such a routine, see the section Shutdown Request, NPT Users Guide"

stackTxRestartRtn
Expects a pointer to the function that the MUX will call when packet transmission has been suspended to tell the network service that it can continue transmitting packets

stackErrorRtn
Expects a pointer to the function that the MUX will call to give errors to the network service.

type
Expects a value that indicates the protocol type. The MUX uses this type to prioritize a network service as well as to modify its capabilities. For example, a network service of type MUX_PROTO_SNARF has the highest priority (see the description of protocol prioritizing provided in Network Protocol Toolkit User's Guide Aside from MUX_PROTO_SNARF and MUX_PROTO_PROMISC, valid network service types include any of the values specified in RFC 1700, or can be user-defined.
If the type is MUX_PROTO_OUTPUT, this network service is an output protocol and all packets that are going to be output on this device are passed to a stackRcvRtn( ) routine rather than being sent down to the device. This can be used by a network service that needs to send packets directly to another network service, or in a loop-back test. If the stackRcvRtn( ) returns OK, the packet is consumed and as no longer available. The stackRcvRtn( ) for an output protocol may return ERROR to indicate that it wants to look at the packet without consuming it.

pProtoName
Expects a pointer to a character string for the name of this network service. This string can be NULL, in which case a network service name is assigned internally.

pNetCallbackId
Expects a pointer to a structure defined by the protocol. This argument is passed up to the protocol as the first argument of all the callbacks. This argument corresponds to the pSpare argument in muxBind( )

pNetSvcInfo
Reference to an optional structure specifying network service layer information needed by the driver

pNetDrvInfo
Reference to an optional structure specifying network driver information needed by the Network protocol sublayer

RETURNS

A Cookie which uniquely represents the binding instance, or NULL if the bind fails.

ERRNO

S_muxLib_NO_DEVICE, S_muxLib_END_BIND_FAILED, S_muxLib_NO_TK_DEVICE,
S_muxLib_NOT_A_TK_DEVICE, S_muxLib_ALREADY_BOUND,
S_muxLib_ALLOC_FAILED

muxTkReceive( )

NAME

muxTkReceive( ) - Receive a packet from a NPT driver.

SYNOPSIS

STATUS muxTkReceive
    (
    void *   pCookie,        /* Cookie passed in endLoad call */
    M_BLK_ID pMblk,          /* A buffer passed to us. */
    long     netSvcOffset,   /* offset to Network datagram in the packet */
    long     netSvcType,     /* Network service type */
    BOOL     uniPromiscuous, /* set to TRUE when Driver in promiscuous mode */
    void *   pSpareData      /* out of band data */
    )

DESCRIPTION

This is the routine that the NPT driver calls to hand a packet to the MUX. This routine forwards the received mBlk chain to the network service sublayer by calling the registered stackRcvRtn( ).
Depending on the protocol type(MUX_PROTO_SNARF, MUX_PROTO_PROMISC, etc.) this routine either forwards the received packet chain unmodified or it updates the data pointer in the mBlk to reference the network service header

pCookie
Expects the cookie returned by the driver's endLoad( ) function;

pMblk
Expects a pointer to the mBlk structure containing the packet that has been received

netSvcOffset
Expects an offset to the Network Service header within the packet

netSvcType
Expects the network service type

uniPromiscuous
Expects a boolean set to TRUE when driver is in promisucous mode and receives a unicast or a multicast packet not intended for this device. When TRUE the packet is not handed over to network services other than those registered as SNARF or PROMISCUOUS

pSpareData
Expects a pointer to any spare data the driver needs to pass up to the network service layer, or NULL

RETURNS

OK or ERROR.

ERRNO

S_muxLib_NO_DEVICE

muxTkSend( )

NAME

muxTkSend( ) - send a packet out on a Toolkit or END network interface

SYNOPSIS

STATUS muxTkSend
    (
    void *   pCookie,    /* returned by muxTkBind() */
    M_BLK_ID pNBuff,     /* data to be sent */
    char *   dstMacAddr, /* destination MAC address */
    USHORT   netType,    /* network protocol that is calling us: redundant? */
    void *   pSpareData  /* spare data passed on each send */
    )

DESCRIPTION

This routine uses pCookie to find a specific network interface and use that driver's send routine to transmit a packet.
The transmit entry point for an NPT driver uses the following prototype:
STATUS nptSend
    (
    void *    pDevCookie,     /* Device cookie */
    M_BLK_ID  pPkt,           /* Network packet to transmit */
    char *    pDstAddr,       /* Destination MAC address */
    long      netType         /* Network service type */
    void *    pSpareData      /* Optional Network service data */
    )
The transmit entry point for an END driver still uses the original prototype:
STATUS endSend
    (
    void *    pDevCookie,     /* Device cookie */
    M_BLK_ID  pPkt,           /* Network packet to transmit */
    )
An END driver must continue to provide the addressForm( ) entry point to construct the appropriate link-level header. The pDst and pSrc M_BLK arguments to that routine supply the link-level addresses with the mData and mLen fields. The reserved field of the destination M_BLK contains the network service type. Both arguments MUST be treated as READ ONLY.

pCookie
Expects the Cookie returned from muxTkBind( ). This Cookie identifies the device to which the MUX has bound this protocol.

pNBuff
The network packet to be sent.

dstMacAddr
Destination MAC address to which packet is to be sent

netType
Network service type that will be used to identify the payload type in the MAC frame.

pSpareData
Reference to any additional data the network service wants to pass to the driver during the send operation. frame.

RETURNS

OK, ENETDOWN if pCookie doesn't represent a valid device,
or ERROR if the driver's send( ) routine fails.

ERRNO

S_muxLib_NO_DEVICE

muxTkPollSend( )

NAME

muxTkPollSend( ) - send a packet out in polled mode to an END or NPT interface

SYNOPSIS

STATUS muxTkPollSend
    (
    void *   pCookie,    /* returned by muxTkBind() */
    M_BLK_ID pNBuff,     /* data to be sent */
    char *   dstMacAddr, /* destination MAC address */
    USHORT   netType,    /* network protocol that is calling us: redundant? */
    void *   pSpareData  /* spare data passed on each send */
    )

DESCRIPTION

This routine uses pCookie to find a specific network interface and use that driver's pollSend( ) routine to transmit a packet.
This API effectively replaces the muxPollSend( ) for both END and NPT drivers.
For a NPT driver its pollSend( ) entry point is called based on the new prototype:
STATUS nptPollSend
    (
    void *    pDevCookie,     /* Device cookie */
    M_BLK_ID  pPkt,           /* Network packet to transmit */
    char *    pDstAddr,       /* Destination MAC address */
    long      netType         /* Network service type */
    void *    pSpareData      /* Optional Network service data */
    )
The transmit entry point for an END driver still uses the original prototype:
STATUS endPollSend
    (
    void *    pDevCookie,     /* Device cookie */
    M_BLK_ID  pPkt,           /* Network packet to transmit */
    )
An END driver must continue to provide the addressForm( ) entry point to construct the appropriate link-level header. The pDst and pSrc M_BLK arguments to that routine supply the link-level addresses with the mData and mLen fields. The reserved field of the destination M_BLK contains the network service type. Both arguments MUST be treated as READ ONLY.

pCookie
Expects the Cookie returned from muxTkBind( ). This Cookie identifies the device to which the MUX has bound this protocol.

pNBuff
The network packet to be sent.

dstMacAddr
Destination MAC address to which packet is to be sent

netType
Network service type that will be used to identify the payload data in the MAC frame.

pSpareData
Reference to any additional data the network service wants to pass to the driver during the send operation. frame.

RETURNS

OK, ENETDOWN if pCookie doesn't represent a valid device, or ERROR if the driver's pollSend( ) routine fails.

ERRNO

S_muxLib_NO_DEVICE

muxTkPollReceive( )

NAME

muxTkPollReceive( ) - poll for a packet from a NPT or END driver

SYNOPSIS

STATUS muxTkPollReceive
    (
    void *   pCookie, /* cookie from muxTkBind routine */
    M_BLK_ID pNBuff,  /* a vector of buffers passed to us */
    void *   pSpare   /* a reference to spare data is returned here */
    )

DESCRIPTION

This is the routine that an upper layer can call to poll for a packet. Any service type retrieved from the MAC frame is passed via the reserved member of the M_BLK header.
This API effectively replaces muxPollReceive( ) for both END and NPT drivers.
For a NPT driver its pollRcv( ) entry point is called based on the new prototype:
STATUS nptPollRcv
    (
    void *    pDevCookie,     /* Device cookie */
    M_BLK_ID  pPkt,           /* Network packet buffer */
    long *    pNetSvc,        /* Service type from MAC frame */
    long *    pNetOffset,     /* Offset to network packet */
    void *    pSpareData      /* Optional Network service data */
    )
The pollReceive( ) entry point for an END driver uses the original prototype:
STATUS endPollRcv
    (
    void *    pDevCookie,     /* Device cookie */
    M_BLK_ID  pPkt,           /* Network packet buffer */
    )
An END driver must continue to provide the packetDataGet( ) entry point

pCookie
Expects the cookie that was returned from muxBind( ) or muxTkBind( ). This "cookie" is an identifier for the driver.

pNBuff
Expects a pointer to a buffer chain into which incoming data will be put.

pSpareData
pointer to any optional spare data provided by a NPT driver. If not NULL this *pSpareData will always be set to NULL for an END driver.

RETURNS

OK, EAGAIN if no packet was available, ENETDOWN if the pCookie
does not represent a loaded driver, or an error value returned
from the driver's registered pollReceive( ) function.

ERRNO

S_muxLib_NO_DEVICE

muxTkLib

NAME

ROUTINES

DESCRIPTION

INCLUDE FILES

SEE ALSO

muxTkDrvCheck( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

muxTkBind( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO

muxTkReceive( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO

muxTkSend( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO

muxTkPollSend( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO

muxTkPollReceive( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO