VxWorks Reference Manual : Libraries
muxLib - MUX network interface library
muxLibInit( ) - initialize global state for the MUX
muxDevLoad( ) - load a driver into the MUX
muxDevStart( ) - start a device by calling its start routine
muxDevStop( ) - stop a device by calling its stop routine
muxShow( ) - display configuration of devices registered with the MUX
muxBind( ) - create a binding between a network service and and END
muxSend( ) - send a packet out on a network interface
muxPollSend( ) - send a packet on a network interface
muxPollReceive( ) - poll for a packet from a device driver
muxIoctl( ) - send control information to the MUX or to a device
muxMCastAddrAdd( ) - add a multicast address to a device's multicast table
muxMCastAddrDel( ) - delete a multicast address from a device's multicast table
muxMCastAddrGet( ) - get the multicast address table from the MUX/Driver
muxUnbind( ) - detach a network service from the specified device
muxDevUnload( ) - unloads a device from the MUX
muxLinkHeaderCreate( ) - attach a link-level header to a packet
muxAddressForm( ) - form a frame with a link-layer address
muxPacketDataGet( ) - return the data from a packet
muxPacketAddrGet( ) - get addressing information from a packet
endFindByName( ) - find a device using its string name
muxDevExists( ) - tests whether a device is already loaded into the MUX
muxAddrResFuncAdd( ) - add an address resolution function
muxAddrResFuncGet( ) - get the address resolution function for ifType/protocol
muxAddrResFuncDel( ) - delete an address resolution function
This library provides the routines that define the MUX interface, a facility that handles communication between the data link layer and the network protocol layer. Using the MUX, the VxWorks network stack has decoupled the data link and network layers. Thus, drivers and services no longer need knowledge of each other's internals. As a result, the network driver and network service are nearly independent of each another. This independence makes it much easier to add a new drivers or services. For example, if you add a new MUX-based "END" driver, all existing MUX-based services can use the new driver. Likewise, if you add a new MUX-based service, any existing END can use the MUX to access the new service.
errno.h, lstLib.h, logLib.h, string.h, m2Lib.h, bufLib.h, if.h, end.h, muxLib.h, vxWorks.h, taskLib.h, stdio.h, errnoLib.h, if_ether.h, netLib.h, semLib.h, rebootLib.h
muxLib, Network Protocol Toolkit Programmer's Guide
muxLibInit( ) - initialize global state for the MUX
STATUS muxLibInit (void)
This routine initializes all global states for the MUX.
OK or ERROR.
muxDevLoad( ) - load a driver into the MUX
void * muxDevLoad ( int unit, /* unit number of device */ END_OBJ * (* endLoad) (char* , void* ), /* load function of the driver */ char * pInitString, /* init string for this driver */ BOOL loaning, /* we loan buffers */ void * pBSP /* for BSP group */ )
The muxDevLoad( ) routine loads a network driver into the MUX. Internally, this routine calls the specified endLoad routine to initialize the software state of the device. After the device is initialized, muxDevStart( ) must be called to start the device.
- unit
- Expects the unit number of the device.
- endLoad
- Expects a pointer to the network driver's endLoad( ) or nptLoad( ) entry point.
- pInitString
- Expects a pointer to an initialization string, typically a colon-delimited list of options. The muxDevLoad( ) routine passes this along blindly to the endLoad function.
- loaning
- Currently unused.
- pBSP
- This argument is passed blindly to the driver, which may or may not use it. It is provided so that the BSP can pass in tables of functions that the driver can use but that are specific to the particular BSP on which it runs.
A cookie representing the new device, or NULL if an error occurred.
S_muxLib_LOAD_FAILED
muxDevStart( ) - start a device by calling its start routine
STATUS muxDevStart ( void * pCookie /* device identifier from muxDevLoad() routine */ )
This routine starts a device that has already been initialized and loaded into the MUX with muxDevLoad( ). muxDevStart( ) activates the network interfaces for a device, and calls the device's endStart( ) or nptStart( ) routine, which registers the driver's interrupt service routine and does whatever else is needed to allow the device to handle receiving and transmitting. This call to endStart( ) or nptStart( ) puts the device into a running state.
- pCookie
- Expects the cookie returned from the muxDevLoad( ) call that loaded this device. This cookie identifies the device.
OK, ENETDOWN if pCookie does not represent a valid device,
or ERROR if the endStart( ) routine for the device fails.
S_muxLib_NO_DEVICE
muxDevStop( ) - stop a device by calling its stop routine
STATUS muxDevStop ( void * pCookie /* device identifier from muxDevLoad() routine */ )
This routine stops the device specified by the pCookie parameter. muxDevStop( ) calls the device's endStop( ) or nptStop( ) routine.
- pCookie
- Expects the cookie returned as the function value of the muxDevLoad( ) call for this device. This cookie identifies the device.
OK, ENETDOWN if pCookie does not represent a valid device, or
ERROR if the endStop( ) or nptStop( ) routine for the device fails.
S_muxLib_NO_DEVICE
muxShow( ) - display configuration of devices registered with the MUX
void muxShow ( char * pDevName, /* pointer to device name, or NULL for all */ int unit /* unit number for a single device */ )
If the pDevName and unit arguments specify an existing device, this routine reports the name and type of each protocol bound to it. Otherwise, if pDevName is NULL, the routine displays the entire list of existing devices and their associated protocols.
- pDevName
- A string that contains the name of the device, or a null pointer to indicate "all devices."
- unit
- If pDevName is being used to specify a single device, unit should hold the unit number of that device.
N/A
muxBind( ) - create a binding between a network service and and END
void * muxBind ( char * pName, /* interface name, for example, ln, */ int unit, /* unit number */ BOOL (* stackRcvRtn) (void* )
A network service uses this routine to bind to an END specified by the pName and unit arguments (for example, ln and 0, ln and 1, or ei and 0).
This routine should only be used to bind to drivers that use the old END driver callback function prototypes. NPT drivers, or END drivers that use the newer callback function prototypes, should use muxTkBind( ) instead. See the Network Protocol Toolkit Programmer's Guide for more information on when to use muxBind( ) and muxTkBind( ).
The type argument assigns a network service to one of several classes. Standard services receive the portion of incoming data associated with type values from RFC 1700. Only one service for each RFC 1700 type value may be bound to an END.
Services with type MUX_PROTO_SNARF provide a mechanism for bypassing the standard services for purposes such as firewalls. These services will get incoming packets before any of the standard services.
Promiscuous services with type MUX_PROTO_PROMISC receive any packets not consumed by the snarf or standard services.
The MUX allows multiple snarf and promiscuous services but does not coordinate between them. It simply delivers available packets to each service in FIFO order. Services that consume packets may prevent "downstream" services from receiving data if the desired packets overlap.
An output service (with type MUX_PROTO_OUTPUT) receives outgoing data before it is sent to the device. This service type allows two network services to communicate directly and provides a mechanism for loop-back testing. Only one output service is supported for each driver.
The MUX calls the registered stackRcvRtn whenever it receives a packet of the appropriate type. If that routine returns TRUE, the packet is not offered to any remaining services (or to the driver in the case of an output services). A service (including an output service) may return FALSE to examine a packet without consuming it. See the description of a stackRcvRtn( ) in the Network Protocol Toolkit Programmer's Guide for additional information about the expected behavior of that routine.
The stackShutdownRtn argument provides a function which allows the MUX to shut down the service. See the Network Protocol Toolkit Programmer's Guide for a description of how to write such a routine.
The pProtoName argument provides the name of the service as a character string. A service name is assigned internally if the argument is NULL.
The pSpare argument registers a pointer to data defined by the service. This argument is passed to the service in calls to the callback routines.
A cookie identifying the binding between the service and driver,
or NULL if an error occurred.
S_muxLib_NO_DEVICE, S_muxLib_ALREADY_BOUND, S_muxLib_ALLOC_FAILED
muxSend( ) - send a packet out on a network interface
STATUS muxSend ( void * pCookie, /* protocol/device binding from muxBind() */ M_BLK_ID pNBuff /* data to be sent */ )
This routine transmits a packet for a specific service using the pCookie value returned during the bind, which indicates the network interface through which the packet is to be transmitted.
- pCookie
- Expects the cookie returned from muxBind( ). This cookie identifies the binding between the service and device.
- pNBuff
- Expects a pointer to the buffer that contains the packet you want to transmit. Before you call muxSend( ), you need to put the addressing information at the head of the buffer. To do this, call muxAddressForm( ).
Also, the buffer should probably be reserved from the MUX-managed memory pool. To reserve a buffer from this pool, the service should call muxBufAlloc( ).
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 muxSend( ) 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.
OK, or ENETDOWN if pCookie does not represent a valid binding,
or an error if the driver's endSend( ) routine fails.
S_muxLib_NO_DEVICE
muxPollSend( ) - send a packet on a network interface
STATUS muxPollSend ( void * pCookie, /* binding instance from muxBind() */ M_BLK_ID pNBuff /* data to be sent */ )
This routine has been deprecated in favor of muxTkPollSend( )
This routine transmits a packet for a specific service using the pCookie value returned during the bind, which indicates the network interface through which the packet is transmitted. The pNBuff argument is a buffer (mBlk) chain which contains the packet to be sent.
OK, ENETDOWN if pCookie doesn't represent a valid device,
ERROR if the device type is not recognized, or an error if the
endPollSend( ) routine for the driver fails.
S_muxLib_NO_DEVICE
muxPollReceive( ) - poll for a packet from a device driver
STATUS muxPollReceive ( void * pCookie, /* binding instance from muxBind() */ M_BLK_ID pNBuff /* a vector of buffers passed to us */ )
This routine has been deprecated in favor of muxTkPollReceive( )
This is the routine that an upper layer can call to poll for a packet.
- pCookie
- Expects the cookie that was returned from muxBind( ). This cookie indicates which driver to query for available data.
- pNBuff
- Expects a pointer to a buffer chain into which incoming data will be put.
OK, ENETDOWN if the pCookie argument
does not represent a loaded driver, or an error value returned
from the driver's registered endPollReceive( ) function.
S_muxLib_NO_DEVICE
muxIoctl( ) - send control information to the MUX or to a device
STATUS muxIoctl ( void * pCookie, /* service/device binding from muxBind()/muxTkBind() */ int cmd, /* command to pass to ioctl */ caddr_t data /* data need for command in cmd */ )
This routine gives the service access to the network driver's control functions. The MUX itself can implement some of the standard control functions, so not all commands necessarily pass down to the device. Otherwise, both command and data pass to the device without modification.
Typical uses of muxIoctl( ) include commands to start, stop, or reset the network interface, or to add or configure MAC and network addresses.
- pCookie
- Expects the cookie returned from muxBind( ) or muxTkBind( ). This cookie indicates the device to which this service is bound.
- cmd
- Expects a value indicating the control command you want to execute. For valid cmd values, see the description of the endIoctl( ) and nptIoctl( ) routines provided in the Network Protocol Toolkit Programmer's Guide .
- data
- Expects the data or a pointer to the data needed to carry out the command specified in cmd.
OK, ENETDOWN if pCookie does not represent a bound device,
or ERROR if the command fails.
S_muxLib_NO_DEVICE
muxMCastAddrAdd( ) - add a multicast address to a device's multicast table
STATUS muxMCastAddrAdd ( void * pCookie, /* binding instance from muxBind() or muxTkBind() */ char * pAddress /* address to add to the table */ )
This routine adds an address to the multicast table maintained by a device. This routine calls the driver's endMCastAddrAdd( ) or nptMCastAddrAdd( ) routine to accomplish this.
If the device does not support multicasting, muxMCastAddrAdd( ) will return ERROR and errno will be set to ENOTSUP (assuming the driver has been written properly).
- pCookie
- Expects the cookie returned from the muxBind( ) or muxTkBind( ) call. This cookie identifies the device to which the MUX has bound this service.
- pAddress
- Expects a pointer to a character string containing the address you want to add.
OK, ENETDOWN if pCookie doesn't represent a valid device,
or ERROR if the device's endMCastAddrAdd( ) function fails.
S_muxLib_NO_DEVICE
muxMCastAddrDel( ) - delete a multicast address from a device's multicast table
STATUS muxMCastAddrDel ( void * pCookie, /* binding instance from muxBind() or muxTkBind() */ char * pAddress /* Address to delete from the table. */ )
This routine deletes an address from the multicast table maintained by a device by calling that device's endMCastAddrDel( ) or nptMCastAddrDel( ) routine.
If the device does not support multicasting, muxMCastAddrAdd( ) will return ERROR and errno will be set to ENOTSUP (assuming the driver has been written properly).
- pCookie
- Expects the cookie returned from muxBind( ) or muxTkBind( ) call. This cookie identifies the device to which the MUX bound this service.
- pAddress
- Expects a pointer to a character string containing the address you want to delete.
OK, ENETDOWN if pCookie does not represent a valid driver,
or ERROR if the driver's registered endMCastAddrDel( ) or
nptMCastAddrDel( ) function fails.
S_muxLib_NO_DEVICE
muxMCastAddrGet( ) - get the multicast address table from the MUX/Driver
int muxMCastAddrGet ( void * pCookie, /* binding instance from muxBind() or muxTkBind() */ MULTI_TABLE * pTable /* pointer to a table to be filled and returned. */ )
This routine writes the list of multicast addresses for a specified device into a buffer. To get this list, it calls the driver's own endMCastAddrGet( ) or nptMCastAddrGet( ) routine.
- pCookie
- Expects the cookie returned from muxBind( ) or muxTkBind( ) call. This cookie indicates the device to which the MUX has bound this service.
- pTable
- Expects a pointer to a MULTI_TABLE structure. You must have allocated this structure at some time before the call to muxMCastAddrGet( ). The MULTI_TABLE structure is defined in end.h as:
typedef struct multi_table { int tableLen; /* length of table in bytes */ char * pTable; /* pointer to entries */ } MULTI_TABLE;
OK, ENETDOWN if pCookie does not represent a valid driver, or ERROR if the driver's registered endMCastAddrGet( ) or nptMCastAddrGet( ) routine fails.
S_muxLib_NO_DEVICE
muxUnbind( ) - detach a network service from the specified device
STATUS muxUnbind ( void * pCookie, /* binding cookie from muxBind() or muxTkBind() */ long type, /* type passed to muxBind() or muxTkBind() call */ FUNCPTR stackRcvRtn /* pointer to stack receive routine */ )
This routine disconnects a network service from the specified device. The pCookie argument indicates the service/device binding returned by the muxBind( ) or muxTkBind( ) routine. The type and stackRcvRtn arguments must also match the values given to the original muxBind( ) or muxTkBind( ) call.
If muxUnbind( ) returns ERROR, and errno is set to EINVAL, this indicates that the device is not bound to the service.
OK, ERROR if muxUnbind( ) fails.
EINVAL, S_muxLib_NO_DEVICE
muxDevUnload( ) - unloads a device from the MUX
STATUS muxDevUnload ( char * pName, /* a string containing the name of the device for example, */ /* or ei */ int unit /* the unit number */ )
This routine unloads a device from the MUX. This breaks any network connections that use the device. When this routine is called, each service bound to the device disconnects from it with the stackShutdownRtn( ) routine that was registered by the service. The stackShutdownRtn( ) should call muxUnbind( ) to detach from the device. Then, muxDevUnload( ) calls the device's endUnload( ) or nptUnload( ) routine.
- pName
- Expects a pointer to a string containing the name of the device, for example ln or ei
- unit
- Expects the unit number of the device indicated by pName
OK on success, ERROR if the specified device was not found
or some other error occurred, or an error returned by the driver's
unload( ) routine.
S_muxLib_UNLOAD_FAILED, S_muxLib_NO_DEVICE
muxLinkHeaderCreate( ) - attach a link-level header to a packet
M_BLK_ID muxLinkHeaderCreate ( void * pCookie, /* protocol/device binding from muxBind() */ M_BLK_ID pPacket, /* structure containing frame contents */ M_BLK_ID pSrcAddr, /* structure containing source address */ M_BLK_ID pDstAddr, /* structure containing destination address */ BOOL bcastFlag /* use broadcast destination (if available)? */ )
This routine constructs a link-level header using the source address of the device indicated by the pCookie argument as returned from the muxBind( ) routine.
The pDstAddr argument provides an M_BLK_ID buffer containing the link-level destination address. Alternatively, the bcastFlag argument, if TRUE, indicates that the routine should use the link-level broadcast address, if available for the device. Although other information contained in the pDstAddr argument must be accurate, the address data itself is ignored in that case.
The pPacket argument contains the contents of the resulting link-level frame. This routine prepends the new link-level header to the initial mBlk in that network packet if space is available or allocates a new mBlk-clBlk-cluster triplet and prepends it to the mBlk chain. When construction of the header is complete, it returns an M_BLK_ID that points to the initial mBlk in the assembled link-level frame.
M_BLK_ID or NULL.
S_muxLib_INVALID_ARGS
muxAddressForm( ) - form a frame with a link-layer address
M_BLK_ID muxAddressForm ( void * pCookie, /* protocol/device binding from muxBind() */ M_BLK_ID pMblk, /* structure to contain packet */ M_BLK_ID pSrcAddr, /* structure containing source address */ M_BLK_ID pDstAddr /* structure containing destination address */ )
This routine accepts the source and destination addressing information in the pSrcAddr and pDstAddr mBlks, and a data buffer in pMblk, and returns an mBlk that contains the assembled link-level header, while prepending this header to the data buffer in pMblk.
This routine prepends the link-level header into pMblk if there is enough space available or it allocates a new mBlk-clBlk-cluster and prepends the new mBlk to the mBlk chain passed in pMblk otherwise.
The pDstAddr.mBlkHdr.reserved field should be set to the network service type.
- pCookie
- Expects the cookie returned from the muxBind( ). This cookie indicates the device to which the MUX has bound this protocol.
- pMblk
- Expects a pointer to the mBlk structure that contains the packet.
- pSrcAddr
- Expects a pointer to the mBlk that contains the source address.
- pDstAddr
- Expects a pointer to the mBlk that contains the destination address.
This routine is used only with ENDs, and is not needed for NPT drivers.
M_BLK_ID or NULL.
S_muxLib_NO_DEVICE
muxPacketDataGet( ) - return the data from a packet
STATUS muxPacketDataGet ( void * pCookie, /* service/device binding from muxBind() */ M_BLK_ID pMblk, /* returns the packet data */ LL_HDR_INFO * pLinkHdrInfo /* returns the packet header information */ )
Any service bound to a driver may use this routine to extract the packet data and remove the link-level header information. This routine copies the header information from the packet referenced in pMblk into the LL_HDR_INFO structure referenced in pLinkHdrInfo.
- pCookie
- Expects the cookie returned from the muxBind( ) call. This cookie indicates the device to which the MUX bound this service.
- pMblk
- Expects a pointer to an mBlk or mBlk cluster representing a packet containing the data to be returned
- pLinkHdrInfo
- Expects a pointer to an LL_HDR_INFO structure into which the packet header information is copied from the incoming mBlk
OK or ERROR if the device type is not recognized.
S_muxLib_NO_DEVICE
muxPacketAddrGet( ) - get addressing information from a packet
STATUS muxPacketAddrGet ( void * pCookie, /* service/device binding from muxBind() */ M_BLK_ID pMblk, /* structure to contain packet */ M_BLK_ID pSrcAddr, /* structure containing source address */ M_BLK_ID pDstAddr, /* structure containing destination address */ M_BLK_ID pESrcAddr, /* structure containing the end source */ M_BLK_ID pEDstAddr /* structure containing the end destination */ )
This routine takes the cookie that was handed back by muxBind( ), an M_BLK_ID that came from a device and up to four M_BLK_ID's that can receive data pointers.
The routine returns appropriate information on the immediate source, immediate destination, ultimate source and, ultimate destination addresses from the packet pointed to in the first M_BLK_ID. This routine is a pass through to the device's own routine which knows how to interpret packets that it has received.
- pCookie
- Expects the cookie returned from the muxBind( ) call. This cookie indicates the device to which the MUX bound this service.
- pMblk
- Expects an M_BLK_ID representing packet data from which the addressing information is to be extracted
- pSrcAddr
- Expects NULL or an M_BLK_ID which will hold the local source address extracted from the packet
- pDstAddr
- Expects NULL or an M_BLK_ID which will hold the local destination address extracted from the packet
- pESrcAddr
- Expects NULL or an M_BLK_ID which will hold the end source address extracted from the packet
- pEDstAddr
- Expects NULL or an M_BLK_ID which will hold the end destination address extracted from the packet
OK or ERROR.
S_muxLib_NO_DEVICE
endFindByName( ) - find a device using its string name
END_OBJ * endFindByName ( char * pName, /* device name to search for */ int unit )
This routine takes a string name and a unit number and finds the device that has that name/unit combination.
A pointer to an END_OBJ or NULL (if the device is not found).
muxDevExists( ) - tests whether a device is already loaded into the MUX
BOOL muxDevExists ( char * pName, /* string containing a device name (ln, ei, ...) */ int unit /* unit number */ )
This routine takes a string device name (for example, ln or ei) and a unit number. If this device is already known to the MUX, it returns TRUE. Otherwise, this routine returns FALSE.
- pName
- Expects a pointer to a string containing the device name
- unit
- Expects the unit number of the device
TRUE if the device exists, else FALSE.
muxAddrResFuncAdd( ) - add an address resolution function
STATUS muxAddrResFuncAdd ( long ifType, /* Media interface type, for instance from m2Lib.h */ long protocol, /* Service type, for instance from RFC 1700 */ FUNCPTR addrResFunc /* Function to call. */ )
This routine takes a driver type and service type and a pointer to an address resolution function that is appropriate to this combination of driver and service, and installs that function for later retrieval by muxAddrResFuncGet( ).
If the driver does not register itself as an Ethernet driver, and if the link layer requires hardware address resolution, the driver must install an address resolution function with muxAddrResFuncAdd( ) at some point before calling the network service's attach( ) routine. (For registered Ethernet devices, VxWorks will automatically install arpresolve( ) as the address resolution function.)
See the Network Protocol Toolkit Programmer's Guide . for additional requirements for an address resolution function designed for use with the IP sublayer.
If using the END model, the ifType and protocol arguments are restricted to the values in m2Lib.h or RFC 1700. In the NPT model, these restrictions are removed.
- ifType
- Expects a media interface or network driver type, such as can be found in m2Lib.h
- protocol
- Expects a network service or protocol type, such as can be found in RFC 1700. Look for the values under ETHER TYPES. For example, Internet IP would be indentified as 2048 (0x800 hexadecimal).
- addrResFunc
- Expects a pointer to an address resolution function for this combination of driver type and service type. The prototype for this function is the same as that for arpresolve( ):
int arpresolve { struct arpcom * ac, struct rtentry * rt, struct mbuf * m, struct sockaddr * dst, u_char * desten, }
OK, or ERROR.
muxAddrResFuncGet( ) - get the address resolution function for ifType/protocol
FUNCPTR muxAddrResFuncGet ( long ifType, /* ifType from m2Lib.h */ long protocol /* protocol from RFC 1700 */ )
This routine takes an ifType (e.g. from m2Lib.h) and a protocol or service (e.g. from RFC 1700) and returns a pointer to the address resolution function registered for this ifType/protocol pair. If no such function exists then NULL is returned.
If using the END model, the ifType and protocol arguments are restricted to the m2Lib.h or RFC 1700 values. In the NPT model, this restriction is removed.
- ifType
- Expects a media interface or network driver type, such as those found in m2Lib.h
- protocol
- Expects a network service or protocol type such as those found in RFC 1700. Look for the values under ETHER TYPES. For example, Internet IP would be indentified as 2048 (0x800 hexadecimal).
FUNCPTR to the routine or NULL.
muxAddrResFuncDel( ) - delete an address resolution function
STATUS muxAddrResFuncDel ( long ifType, /* ifType of function you want to delete */ long protocol /* protocol from which to delete the function */ )
This function takes an ifType (for instance, those from m2Lib.h) and a protocol (for instance, those from RFC 1700) and deletes the associated address resolution function from the table of registered address resolution functions (if such exists).
If using the END model, the ifType and protocol arguments are restricted to the m2Lib.h or RFC 1700 values. In the NPT model, this restriction is removed.
- ifType
- Expects a media interface or network driver type, for instance from m2Lib.h
- protocol
- Expects a network service or protocol type, for instance from RFC 1700. Look for the values under ETHER TYPES. For example, Internet IP would be indentified as 2048 (0x800 hexadecimal).
OK or ERROR.