muxTkLib

NAME

muxTkLib - MUX toolkit Network Interface Library

ROUTINES

muxTkDrvCheck( ) - checks if the device is an NPT or an END interface
muxTkCookieGet( ) - returns the cookie for a device
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 extend the original release of the MUX interface.
A NPT driver is an enhanced 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 between the network service (or network protocol) and the MUX. This service sublayer may be built in to the network service or protocol rather than being a separate component.

INCLUDE FILES

vxWorks.h, taskLib.h, stdio.h, errno.herrnoLib.h, lstlib.h, logLib.h, string.h, m2Lib.h, net/if.h, bufLib.h, semlib.h, end.h, muxLib.h, muxTkLib.h, netinet/if_ether.h, net/mbuf.h

OS Libraries : Routines

muxTkDrvCheck( )

NAME

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

SYNOPSIS

int muxTkDrvCheck
    (
    char * pDevName           /* device name */
    )

DESCRIPTION

This function returns 1 if the driver indicated by pDevName is of the Toolkit (NPT) paradigm, and 0 (zero) if it is an END. This routine is called by the network service sublayer so that it can discover the driver type before it binds to it via the MUX.

RETURNS

1 for an NPT driver, 0 for an END or other driver, or ERROR (-1) if no device is found with the given name

muxTkCookieGet( )

NAME

muxTkCookieGet( ) - returns the cookie for a device

SYNOPSIS

void *muxTkCookieGet
    (
    char * pName,             /* Device Name */
    int    unit               /* Device Unit */
    )

DESCRIPTION

This routine returns the cookie for a device.

RETURNS

a cookie to the device or NULL if unsuccessful

muxTkBind( )

NAME

muxTkBind( ) - bind an NPT protocol to a driver

SYNOPSIS

void * muxTkBind
    (
    char * pName,             /* interface name, for example, ln, ei,... */
    int    unit,              /* unit number */
    BOOL (* stackRcvRtn) (void* ,long, M_BLK_ID, void * ),
                              /* receive function to be called. */
    STATUS (* stackShutdownRtn) (void * ),
                              /* routine to call to shutdown the stack */
    STATUS (* stackTxRestartRtn) (void * ),
                              /* routine to tell the stack it can transmit */
    void (* stackErrorRtn) (void* , END_ERR* ),
                              /* routine to call on an error. */
    long   type,              /* protocol type from RFC1700 and many */
                              /* other sources (for example, 0x800 is IP) */ 
    char * pProtoName,        /* string name for protocol */
    void * pNetCallbackId,    /* returned to network service sublayer */
                              /* during recv */ 
    void * pNetSvcInfo,       /* reference to netSrvInfo structure */
    void * pNetDrvInfo        /* reference to netDrvInfo structure */
    )

DESCRIPTION

A network protocol, network service, or service sublayer uses this routine to bind to a specific driver. This bind routine is valid both for END and NPT drivers, but the specified stack routine parameters must use the NPT function prototypes, and are somewhat different from those used with muxBind( ).
The driver is specified by the pName and unit arguments, (for example, ln and 0, ln and 1, or ei and 0).

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 WindNet TCP/IP Network Programmer's 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 WindNet TCP/IP Network Programmer's Guide
stackTxRestartRtn
Expects a pointer to the function that the MUX will call after packet transmission has been suspended, to tell the network service that it can continue transmitting packets. For a description of how to write this routine, see the WindNet TCP/IP Network Programmer's Guide
stackErrorRtn
Expects a pointer to the function that the MUX will call to give errors to the network service. For a description of how to write this routine, see the section WindNet TCP/IP Network Programmer's Guide
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 WindNet TCP/IP Network Programmer'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.
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.
If the type is MUX_PROTO_OUTPUT, this network service is an output protocol and all packets that are to be output on this device are first passed to stackRcvRtn routine rather than being sent 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, network service, or service sublayer

RETURNS

A cookie that 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,  /* TRUE when driver is 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 its registered stackRcvRtn( ).
Typically, a driver includes an interrupt handling routine to process received packets. It should keep processing to a minimum during interrupt context and then arrange for processing of the received packet within task context.
Once the frame has been validated, the driver should pass it to the MUX with the receiveRtn member of its END_OBJ structure. This routine has the same prototype as (and typically is) muxTkReceive( ).
Depending on the protocol type (for example, MUX_PROTO_SNARF or MUX_PROTO_PROMISC), this routine either forwards the received packet chain unmodified or it changes the data pointer in the mBlk to strip off the frame header before forwarding the packet.

pCookie
Expects the END_OBJ pointer returned by the driver's endLoad( ) or nptLoad( ) function

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

netSvcOffset
Expects an offset into the frame to the point where the data field (the network service layer header) begins

netSvcType
Expects the network service type of the service for which the packet is destined (typically this value can be found in the header of the received frame)

uniPromiscuous
Expects a boolean set to TRUE when driver is in promiscuous 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 * is */
                              /* netType redundant? * */ 
    void *   pSpareData       /* spare data passed on each send */
    )

DESCRIPTION

This routine uses pCookie to find a specific network interface and uses that driver's send routine to transmit a packet.
The transmit entry point for an NPT driver uses the following prototype:
STATUS nptSend
    (
    END_OBJ * pEND,           /* END object */
    M_BLK_ID  pPkt,           /* network packet to transmit */
    char *    pDstAddr,       /* destination MAC address */
    int       netType         /* network service type */
    void *    pSpareData      /* optional network service data */
    )
The transmit entry point for an END driver the following prototype:
STATUS endSend
    (
    void *    pEND,   /* END object */
    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.
To send a fully formed physical layer frame to a device using an NPT driver (which typically forms the frame itself), set the M_L2HDR flag in the mBlk header.
A driver may be written so that it returns the error END_ERR_BLOCK if the driver has insufficient resources to transmit data. The network service sublayer can use this feedback to establish a flow control mechanism by holding off on making any further calls to muxTkSend( ) until the device is ready to restart transmission, at which time the device should call muxTxRestart( ) which will call the service sublayer's stackRestartRtn( ) that was registered for the interface at bind time.

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, formed into an mBlk chain.

dstMacAddr
Destination MAC address to which packet is to be sent, determined perhaps by calling the address resolution function that was registered for this service/device interface.

netType
Network service type of the sending service. This 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.

NOTE

A driver may return END_ERR_BLOCK if it is temporarily unable to complete the send, and then call muxTxRestart( ) to indicate that it is again able to send data. If the driver has been written in this way, muxTkSend( ) will pass the ERR_END_BLOCK back as its own return value and the service can wait for its stackRestartRtn( ) callback routine to be called before trying the send operation again.

RETURNS

OK; ENETDOWN, if pCookie doesn't represent a valid device; or an 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 * is */
                              /* netType 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 routine replaces the muxPollSend( ) routine for both END and NPT drivers.
When using this routine, the driver does not need to call muxAddressForm( ) to complete the packet, nor does it need to prepend an mBlk of type MF_IFADDR containing the destination address.
An NPT driver's pollSend( ) entry point is called based on this prototype:
STATUS nptPollSend
    (
    END_OBJ * pEND,           /* END object */
    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 pollSend( ) entry point for an END uses this prototype:
STATUS endPollSend
    (
    END_OBJ * pEND,   /* END object */
    M_BLK_ID  pPkt,   /* network packet to transmit */
    )
An END driver must 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 muxBind( ) or 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.

RETURNS

OK, ENETDOWN if pCookie doesn't represent a valid device, or an 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 an NPT driver its pollReceive( ) entry point is called based on the new prototype:
STATUS nptPollReceive
    (
    END_OBJ * pEND,           /* END object */
    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
    (
    END_OBJ * pEND,   /* END object */
    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" identifies the driver.

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

pSpareData
A pointer to any optional spare data provided by a NPT driver. Always NULL with 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

muxTkDrvCheck( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

muxTkCookieGet( )

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

NOTE

RETURNS

ERRNO

SEE ALSO

muxTkPollSend( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO

muxTkPollReceive( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO