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( ) - all configured Enhanced Network Drivers
muxBind( ) - bind a protocol to the MUX given a driver name
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 multicast table for a device
muxMCastAddrDel( ) - delete a multicast address from a device's multicast table
muxMCastAddrGet( ) - get the multicast address table from the MUX/Driver
muxUnbind( ) - detach a protocol from the specified driver
muxDevUnload( ) - remove a driver from the MUX
muxAddressForm( ) - form an address into a packet
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 protocols no longer need knowledge of each other's internals. As a result, the network driver and protocol are nearly independent of each another. This independence makes it much easier to add a new drivers or protocols. For example, if you add a new END, all existing MUX-based protocols can use the new driver. Likewise, if you add a new MUX-based protocol, any existing END can use the MUX to access the new protocol.
errno.h, lstLib.h, logLib.h, string.h, m2Lib.h, bufLib.h, if.h, end.h, muxLib.h
muxLib, Network Protocol Toolkit User's Guide
muxLibInit( ) - initialize global state for the MUX
STATUS muxLibInit (void)
This routine initializes all global state for the MUX.
OK or ERROR.
muxDevLoad( ) - load a driver into the MUX
END_OBJ* muxDevLoad ( int unit, /* unit number fo 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( ) 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( ) entry point.
- pInitString
- Expects a pointer to an initialization string, a colon-delimited list of options. The muxDevLoad( ) routine passes this along blindly to the endLoad( ) function.
- loaning
- Expects a boolean value that tells the MUX whether the driver supports buffer loaning on this device. If the low-level device cannot support buffer loaning, passing in TRUE has no effect.
- 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 which are specific to the particular BSP on which it runs.
A pointer to 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 /* a pointer to cookie returned by muxDevLoad() */ )
This routine starts a device that is already initialized and loaded into the MUX. Internally, muxDevStart( ) calls the device's endStart( ), which handles registering the driver's interrupt service routine and whatever else is needed to allow the device to handle receiving and transmitting. This call to endStart( ) provides a device-dependent way to put the device into a running state.
- pCookie
- Expects a pointer to the END_OBJ returned from the muxDevLoad( ) that loaded this driver into the MUX. This "cookie" is an identifier for the device.
OK, ENETDOWN if pCookie does not represent a valid device,
or ERROR if the start routine for the device fails.
S_muxLib_NO_DEVICE
muxDevStop( ) - stop a device by calling its stop routine
STATUS muxDevStop ( void* pCookie /* pointer to cookie that identifies the device */ )
This routine stops the device specified in the pCookie parameter. Internally, muxDevStop( ) calls the device's own stop routine, thus putting the device into a stopped state in a device-dependent manner.
- pCookie
- Expects the pointer returned as the function value of the muxDevLoad( ) call for this device. This pointer identifies the device to which the MUX has bound this protocol.
OK, ENETDOWN if pCookie does not represent a valid device, or
ERROR if the stop routine for the device fails.
S_muxLib_NO_DEVICE
muxShow( ) - all configured Enhanced Network Drivers
void muxShow ( char * pDevName, /* pointer to device name */ int unit /* unit number for the device */ )
If a driver is specified pDevName and unit, this routine reports the name and type of each protocol bound to it. If a pDevName is not given, the entire list of devices and their protocols is shown.
- pDevName
- Expects a pointer to a string containing the device name, or NULL
- unit
- Expects a unit number for the device
N/A
muxBind( ) - bind a protocol to the MUX given a driver name
END_OBJ* muxBind ( char * pName, /* interface name, for example, ln, */ int unit, /* unit number */ BOOL (* stackRcvRtn) (void* )
A protocol uses this routine to bind to a specific driver. The driver is specified by the pName and unit arguments (for example, ln and 0, ln and 1, 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 the MUX sees.
- pName
- Expects a pointer to a character string that contains the name of the device to which this protocol wants to use to send and receive packets.
- unit
- Expects a number which is the unit of the device of the type indicated by pName.
- stackRcvRtn
- Expects a pointer function that the MUX can call when it wants to pass a packet up to the protocol. For a description of how you should write this routine, see the description of a stackRcvRtn( ) provided in Network Protocol Toolkit User's Guide.
- stackShutdownRtn
- Expects a pointer to the function that the MUX can call to shutdown the protocol. For a description of how to write such a routine, see stackShutdownRtn( ) see the description of a stackRcvRtn( ) provided in Network Protocol Toolkit User's Guide.
- stackErrorRtn
- Expects a pointer to the function that the MUX can call to give errors to the protocol.
- type
- Expects a value that indicates the protocol type. The MUX uses this type to prioritize the protocol. For example, a protocol of type MUX_PROTO_SNARF has the highest priority (see the description of protocol prioritizing provided in Network Protocol Toolkit User's Guide: Writing an NPT Protocol. Aside from MUX_PROTO_SNARF and MUX_PROTO_PROMISC, valid protocol types include any of the values specified in RFC1700. If the type is MUX_PROTO_OUTPUT, this protocol is an output protocol and all packets that are going to be output on this device are passed to the stackRcvRtn( ) routine before actually being sent down to the device. This would be useful, for instance, for a network service that needs to send packets directly to another network service, or for loop-back testing. If the stackRcvRtn( ) returns OK, the packet is considered to have been consumed and is no longer available. An output protocol may return ERROR from its stackRcvRtn( ) in order to look at the packet without consuming it.
- pProtoName
- Expects a pointer to a character string for the name of this protocol. This string can be NULL, in which case a protocol name is assigned internally.
- pSpare
- Expects a pointer to a structure defined by the protocol. This argument is passed up to the protocol with each received packet.
A cookie identifying the network driver to which the mux has
bound the protocol.
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, /* cookie that identifies a network interface */ /* by muxBind() */ M_BLK_ID pNBuff /* data to be sent */ )
This routine uses the pCookie value returned during the bind to identify the network interface through which the packet is to be transmitted.
- pCookie
- Expects the pointer returned from muxBind( ). This pointer identifies the device to which the MUX has bound this protocol.
- 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 protocol should call muxBufAlloc( ).
OK, ENETDOWN if pCookie does not represent a valid interface,
or ERROR if the driver's endSend( ) routine fails.
S_muxLib_NO_DEVICE
muxPollSend( ) - send a packet on a network interface
STATUS muxPollSend ( void* pCookie, /* cookie the protocol got from muxBind() */ M_BLK_ID pNBuff /* data to be sent */ )
This routine takes a cookie which was returned by muxBind( ) and uses it to determine which network interface driver should be used in transmitting the data. The routine takes the data pointed to by pNBuff and sends it to the destination specified by calling the functions in that driver.
- pCookie
- Expects the cookie returned from muxBind( ). This Cookie identifies the device to which the MUX has bound the protocol calling muxPollSend( ).
- pNBuff
- Expects a pointer to the buffer(mBlk) chain that contains the packet to be transmitted.
OK, ENETDOWN if pCookie doesn't represent a valid device,
or ERROR if the device type is not recognized or 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, /* cookie passed in endLoad call */ M_BLK_ID pNBuff /* a vector of buffers passed to us */ )
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" is an identifier for the driver.
- pNBuff
- Expects a pointer to a buffer chain into which incoming data will be put.
OK, ENETDOWN if the pCookie
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, /* cookie identifying the device to access */ int cmd, /* command to pass to ioctl */ caddr_t data /* data need for command in cmd */ )
This routine gives the protocol 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 down to the device unmolested.
This routine also lets the protocol change the routine that the MUX uses to pass data up to the protocol as well as the routine that the MUX uses to shutdown the protocol.
- pCookie
- Expects the pointer returned as the function value of muxBind( ). The pointer identifies the device to which this protocol is bound.
- cmd
- Expects a value indicating the control command you want to execute. For valid cmd values, see the description of the endIoctl( ) routine provided in Network Protocol Toolkit User'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 multicast table for a device
STATUS muxMCastAddrAdd ( void* pCookie, /* returned by the muxBind() call */ char * pAddress /* address to add to the table */ )
This routine adds an address to the multicast table maintained for a device. Internally, this function uses pCookie to find the device-specific routine that handles adding an address to the device's multicast table.
- pCookie
- Expects the pointer returned as the function value of the muxBind( ) call. This pointer identifies the device to which the MUX has bound this protocol.
- 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.
ENOTSUP, S_muxLib_NO_DEVICE
muxMCastAddrDel( ) - delete a multicast address from a device's multicast table
STATUS muxMCastAddrDel ( void* pCookie, /* Returned by the muxBind() call */ char* pAddress /* Address to delete from the table. */ )
This routine deletes an address from the multicast table maintained for a device. Internally, this function uses pCookie to find the device-specific routine that handles deleting an address from the device's multicast table.
- pCookie
- Expects the pointer returned as the function value of the muxBind( ) call. This pointer identifies the device to which the MUX bound this protocol.
- 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( ) function
fails.
ENOTSUP, EINVAL, S_muxLib_NO_DEVICE
muxMCastAddrGet( ) - get the multicast address table from the MUX/Driver
int muxMCastAddrGet ( void* pCookie, /* returned by the muxBind() call */ MULTI_TABLE * pTable /* pointer to a table to be filled and returned. */ )
This routine expects a buffer into which it can write the list of multicast addresses for the specified device. Internally, this routine uses pCookie to access the device-specific routine needed to retrieve the multicast address table.
- pCookie
- Expects the pointer returned as the function value of the muxBind( ) call. This pointer identifies the device to which the MUX has bound this protocol.
- pTable
- Expects the 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( ) function fails.
S_muxLib_NO_DEVICE
muxUnbind( ) - detach a protocol from the specified driver
STATUS muxUnbind ( void* pCookie, /* pointer to identifier for device */ long type, /* device type passed in muxBind() call */ FUNCPTR stackRcvRtn /* pointer to stack receive routine */ )
This routine disconnects a protocol from the specified driver.
- pCookie
- Expects the pointer returned as the function value from the muxBind( ) call. This pointer identifies the device to which the MUX has bound this protocol.
- type
- This is the type that you passed down in the muxBind( ) call.
- stackRcvRtn
- Expects a pointer to the stack receive routine you specified when you called muxBind( ) to bind the driver and protocol.
OK, EINVAL if pCookie does not represent a valid driver or
the protocol is not attached, ERROR if muxUnbind( ) fails.
EINVAL, S_muxLib_NO_DEVICE
muxDevUnload( ) - remove a driver 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 driver from the MUX. This breaks any network connections an application might have open. The stackShutdownRtn( ) of each protocol bound to the END via muxBind( ) will be called. Each stackShutdownRtn( ) is expected to call muxUnbind( ) to detach from the END.
- 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, EINVAL or ERROR if the device's registered
endUnload( ) function failed, if the specified device was not found,
or some other error occurred
S_muxLib_UNLOAD_FAILED, S_muxLib_NO_DEVICE
muxAddressForm( ) - form an address into a packet
M_BLK_ID muxAddressForm ( void* pCookie, /* cookie that identifies the device */ 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 through the pSrcAddr and pDstAddr mBlks and returns an M_BLK_ID that points to the assembled link-level header. 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. This routine returns a pointer to an mBlk that contains the link-level header information.
- pCookie
- Expects the pointer returned from the muxBind( ). This pointer identifies 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.
M_BLK_ID or NULL.
S_muxLib_NO_DEVICE
muxPacketDataGet( ) - return the data from a packet
STATUS muxPacketDataGet ( void* pCookie, /* cookie that identifies the device */ M_BLK_ID pMblk, /* returns the packet data */ LL_HDR_INFO * pLinkHdrInfo /* the new data is returned here */ )
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 identifies the device to which the MUX bound this protocol.
- 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, /* cookie that identifies the device */ 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 a pointer to 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 identifies the device to which the MUX bound this protocol.
- 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 END 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 from m2Lib.h */ long protocol, /* Protocol type from RFC 1700 */ FUNCPTR addrResFunc /* Function to call. */ )
This routine takes an ifType from m2Lib.h, a protocol number from RFC 1700 and a pointer to an address resolution function and installs that function for later retrieval by muxAddrResFuncGet( ).
- ifType
- Expects a media interface or network driver type from m2Lib.h
- protocol
- Expects a network service or protocol type from RFC 1700
- addrResFunc
- Expects a pointer to an address resolution function for this driver and protocol
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 (from m2Lib.h) and a protocol (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.
- ifType
- Expects a media interface or network driver type from m2Lib.h
- protocol
- Expects a network service or protocol type from RFC 1700
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 (from m2Lib.h) and a protocol (from RFC 1700) and deletes the associated address resolution routine (if such exists).
- ifType
- Expects a media interface or network driver type from m2Lib.h
- protocol
- Expects a network service or protocol type from RFC 1700
OK or ERROR.