VxWorks Reference Manual : Libraries
etherLib - Ethernet raw I/O routines and hooks
etherOutput( ) - send a packet on an Ethernet interface
etherInputHookAdd( ) - add a routine to receive all Ethernet input packets
etherInputHookDelete( ) - delete a network interface input hook routine
etherOutputHookAdd( ) - add a routine to receive all Ethernet output packets
etherOutputHookDelete( ) - delete a network interface output hook routine
etherAddrResolve( ) - find an Ethernet address for a specified Internet address
etherTypeGet( ) - get the type from an ethernet packet
This library provides utilities that give direct access to Ethernet packets. Raw packets can be output directly to an interface using etherOutput( ). Incoming and outgoing packets can be examined or processed using the hooks etherInputHookAdd( ) and etherOutputHookAdd( ). The input hook can be used to receive raw packets that are not part of any of the supported network protocols. The input and output hooks can also be used to build network monitoring and testing tools.
Normally, the network should be accessed through the higher-level socket interface provided in sockLib. The routines in etherLib should rarely, if ever, be necessary for applications.
All VxWorks Ethernet drivers using the generic MUX/END model support both the input hook and output hook routines. Both hook types are also supported by the following BSD model drivers:
if_cpm - Motorola CPM Ethernet driver
if_eex - Intel EtherExpress 16 network interface driver
if_ei - Intel 82596 Ethernet driver
if_eihk - Intel 82596 Ethernet driver (for hkv3500)
if_elc - SMC 8013WC Ethernet driver
if_elt - 3Com 3C509 Ethernet driver
if_ene - Novell/Eagle NE2000 network driver
if_esmc - Ampro Ethernet2 SMC-91c9x Ethernet driver
if_fei - Intel 82557 Ethernet driver
if_fn - Fujitsu MB86960 NICE Ethernet driver
if_ln - Advanced Micro Devices Am7990 LANCE Ethernet driver
if_mbc - Motorola 68EN302 Ethernet driver
if_sm - shared memory backplane network interface driver
if_sn - National Semiconductor DP83932B SONIC Ethernet driver
if_ultra - SMC Elite Ultra Ethernet driverThe following BSD drivers support only the input hook routines:
if_cs - Crystal Semiconductor CS8900 network interface driver
if_dc - DEC 21x4x Ethernet LAN network interface driver
if_nicEvb - National Semiconductor ST-NIC Ethernet driver (for evb403)
if_sl - Serial Line IP (SLIP) network interface driverThe following BSD drivers support only the output hook routines:
if_ulip - network interface driver for User Level IP (VxSim)
The following BSD drivers do not support either the input hook or output hook routines:
if_loop - software loopback network interface driver
etherLib.h
etherLib, VxWorks Programmer's Guide: Network
etherOutput( ) - send a packet on an Ethernet interface
STATUS etherOutput ( struct ifnet * pIf, /* interface on which to send */ struct ether_header * pEtherHeader, /* Ethernet header to send */ char * pData, /* data to send */ int dataLength /* # of bytes of data to send */ )
This routine sends a packet on the specified Ethernet interface by calling the interface's output routine directly.
The first argument pIf is a pointer to a variable of type struct ifnet which contains some useful information about the network interface. A routine named ifunit( ) can retrieve this pointer from the system in the following way:
struct ifnet *pIf; ... pIf = ifunit ("ln0");If ifunit( ) returns a non-NULL pointer, it is a valid pointer to the named network interface device structure of type struct ifnet. In the above example, pIf points to the data structure that describes the first LANCE network interface device if ifunit( ) is successful.The second argument pEtherHeader should contain a valid Ethernet address of the machine for which the message contained in the argument pData is intended. If the Ethernet address of this machine is fixed and well-known to the user, filling in the structure ether_header can be accomplished by using bcopy( ) to copy the six-byte Ethernet address into the ether_dhost field of the structure ether_header. Alternatively, users can make use of the routine etherAddrResolve( ) which will use ARP (Address Resolution Protocol) to resolve the Ethernet address for a specified Internet address.
OK, or ERROR if the routine runs out of mbufs.
etherInputHookAdd( ) - add a routine to receive all Ethernet input packets
STATUS etherInputHookAdd ( FUNCPTR inputHook, /* routine to receive Ethernet input */ char* pName, /* name of device if MUX/END is being used */ int unit /* unit of device if MUX/END is being used */ )
This routine adds a hook routine that will be called for every Ethernet packet that is received.
The calling sequence of the input hook routine is:
BOOL inputHook ( struct ifnet *pIf, /* interface packet was received on */ char *buffer, /* received packet */ int length /* length of received packet */ )The hook routine should return TRUE if it has handled the input packet and no further action should be taken with it. It should return FALSE if it has not handled the input packet and normal processing (for example, Internet) should take place.The packet is in a temporary buffer when the hook routine is called. This buffer will be reused upon return from the hook. If the hook routine needs to retain the input packet, it should copy it elsewhere.
A call to the function pointed to by the global function pointer etherInputHookRtn should be invoked in the receive routine of every network driver providing this service. For example:
... #include "etherLib.h" ... xxxRecv () ... /* call input hook if any */ if ((etherInputHookRtn != NULL) && (* etherInputHookRtn) (&ls->ls_if, (char *)eh, len)) { return; /* input hook has already processed this packet */ }
OK if the hook was added, or ERROR otherwise.
etherInputHookDelete( ) - delete a network interface input hook routine
void etherInputHookDelete ( FUNCPTR inputHook, char * pName, int unit )
This routine deletes a network interface input hook.
N/A
etherOutputHookAdd( ) - add a routine to receive all Ethernet output packets
STATUS etherOutputHookAdd ( FUNCPTR outputHook /* routine to receive Ethernet output */ )
This routine adds a hook routine that will be called for every Ethernet packet that is transmitted.
The calling sequence of the output hook routine is:
BOOL outputHook ( struct ifnet *pIf, /* interface packet will be sent on */ char *buffer, /* packet to transmit */ int length /* length of packet to transmit */ )The hook is called immediately before transmission. The hook routine should return TRUE if it has handled the output packet and no further action should be taken with it. It should return FALSE if it has not handled the output packet and normal transmission should take place.The Ethernet packet data is in a temporary buffer when the hook routine is called. This buffer will be reused upon return from the hook. If the hook routine needs to retain the output packet, it should be copied elsewhere.
A call to the function pointed to be the global function pointer etherOutputHookRtn should be invoked in the transmit routine of every network driver providing this service. For example:
... #include "etherLib.h" ... xxxStartOutput () /* call output hook if any */ if ((etherOutputHookRtn != NULL) && (* etherOutputHookRtn) (&ls->ls_if, buf0, len)) { /* output hook has already processed this packet */ } else ...
OK if the hook was added, or ERROR otherwise.
etherOutputHookDelete( ) - delete a network interface output hook routine
void etherOutputHookDelete ( FUNCPTR outputHook )
This routine deletes a network interface output hook, which must be supplied as the only argument.
N/A
etherAddrResolve( ) - find an Ethernet address for a specified Internet address
STATUS etherAddrResolve ( struct ifnet * pIf, /* interface on which to send ARP req */ char * targetAddr, /* name or Internet address of target */ char * eHdr, /* where to return the Ethernet addr */ int numTries, /* number of times to try ARPing */ int numTicks /* number of ticks between ARPing */ )
This routine uses the Address Resolution Protocol (ARP) and internal ARP cache to resolve the Ethernet address of a machine that owns the Internet address given in targetAddr.
The first argument pIf is a pointer to a variable of type struct ifnet which identifies the network interface through which the ARP request messages are to be sent out. The routine ifunit( ) is used to retrieve this pointer from the system in the following way:
struct ifnet *pIf; ... pIf = ifunit ("ln0");If ifunit( ) returns a non-NULL pointer, it is a valid pointer to the named network interface device structure of type struct ifnet. In the above example, pIf will be pointing to the data structure that describes the first LANCE network interface device if ifunit( ) is successful.The six-byte Ethernet address is copied to eHdr, if the resolution of targetAddr is successful. eHdr must point to a buffer of at least six bytes.
OK if the address is resolved successfully, or ERROR if eHdr is NULL, targetAddr is invalid, or address resolution is unsuccessful.
etherLib, etherOutput( )
etherTypeGet( ) - get the type from an ethernet packet
USHORT etherTypeGet ( char * pPacket /* pointer to the beginning of the packet */ )
This routine returns a short that is the ethertype (defined in RFC 1700) from either an 802.3 addressed packet or an RFC 894 packet. Most packets are encoded as described in RFC 894 but 802.3 addressing is also recognized.
A USHORT value that is the ethertype, or 0 on error.
etherLib, RFC 894, TCP/IP Illustrated, Volume 1, by Richard Stevens.