RFC 791 Internet protocol version 4. More...

Collaboration diagram for IP:

Data Structures
struct	_MCASTENTRY
	Multicast entry structure. More...
struct	ifnet
	Network interface structure. More...
struct	ip
	Structure of an internet header. More...
struct	ip_opt
struct	pseudo_hdr
struct	_INET_PROTOCOLS
Defines
#define	SIOCSIFMTU 0x1001
	Set maximum transfer unit.
#define	SIOCGIFMTU 0x1002
	Get maximum transfer unit.
#define	SIOCSIFFLAGS 0x1003
	Set interface flags.
#define	SIOCGIFFLAGS 0x1004
	Get interface flags.
#define	SIOCSIFADDR 0x1005
	Set interface address.
#define	SIOCGIFADDR 0x1006
	Get interface address.
#define	SIOCADDMULTI 0x1007
	Add multicast address.
#define	SIOCDELMULTI 0x1008
	Delete multicast address.
#define	NUT_PERFMON_ADD(s, a)
#define	NUT_PERFMON_INC(s)
#define	IP_IS_MULTICAST(_a) ((ntohl(_a) & 0xF0000000U) == 0xE0000000U)
#define	IPVERSION 4
	IP protocol version.
#define	IP_DF 0x4000
	Don't fragment flag.
#define	IP_MF 0x2000
	More fragments flag.
#define	IP_OFFMASK 0x1fff
	Mask for fragmenting bits.
#define	IPOPT_EOL 0
	End of option list.
#define	IPOPT_NOP 1
	No operation.
#define	IPOPT_RR 7
	Record packet route.
#define	IPOPT_TS 68
	Timestamp.
#define	IPOPT_SECURITY 130
	Provide s,c,h,tcc.
#define	IPOPT_LSRR 131
	Loose source route.
#define	IPOPT_SATID 136
	Satnet id.
#define	IPOPT_SSRR 137
	Strict source route.
#define	IPOPT_OPTVAL 0
	Option identifier offset.
#define	IPOPT_OLEN 1
	Option length offset.
#define	IPOPT_OFFSET 2
	Offset within option.
#define	IPOPT_MINOFF 4
	Minimum offset within option.
#define	MAXTTL 255
	Maximum time to live (seconds).
#define	IPDEFTTL 64
	Default time to live.
#define	IPFRAGTTL 60
	Time to live for fragments.
#define	IPTTLDEC 1
	Subtracted from time to live when forwarding.
Typedefs
typedef struct _MCASTENTRY	MCASTENTRY
	Multicast address entry type.
typedef struct ifnet	IFNET
	Network interface type.
typedef struct ip	IPHDR
	Internet header type.
typedef struct ip_opt	IPHDR_OPT
typedef struct _INET_PROTOCOLS	INET_PROTOCOLS
	Linked list of registered Internet protocols.
Functions
int	NutNetIfSetup (NUTDEVICE *dev, uint32_t ip_addr, uint32_t ip_mask, uint32_t gateway)
	Network interface setup.
int	NutNetIfConfig (const char name, void params, uint32_t ip_addr, uint32_t ip_mask)
	Configure a network interface.
int	NutNetIfConfig2 (const char name, void params, uint32_t ip_addr, uint32_t ip_mask, uint32_t gateway)
	Configure a network interface including the default gateway.
int	NutNetIfAddMcastAddr (const char *name, uint32_t ip_addr)
int	NutNetIfDelMcastAddr (const char *name, uint32_t ip_addr)
uint32_t	inet_addr (const char *str)
	Convert decimal dotted ASCII representation into numeric IP address.
char *	inet_ntoa (uint32_t addr)
	Convert numeric IP address into decimal dotted ASCII representation.
char *	inet_mtoa (uint8_t *mac)
	Convert numeric MAC address array into double dotted ASCII representation.
uint16_t	NutIpChkSumPartial (uint16_t ics, const void *buf, int len)
	Calculate a partial IP checksum of a buffer.
uint16_t	NutIpChkSum (uint16_t ics, const void *buf, int len)
	Calculates an the final IP checksum over a block of data.
uint32_t	NutIpPseudoChkSumPartial (uint32_t src_addr, uint32_t dest_addr, uint8_t protocol, int len)
	Calculates the partial IP pseudo checksum.
int	NutRegisterIpHandler (uint8_t prot, int(hdlr)(NUTDEVICE , NETBUF *))
	Register an additional Ethernet protocol handler.
void	NutIpSetInputFilter (NutIpFilterFunc callbackFunc)
	Set filter function for incoming IP datagrams.
void	NutIpInput (NUTDEVICE dev, NETBUF nb)
	Process incoming IP datagrams.
int	NutIpOutput (uint8_t proto, uint32_t dest, NETBUF *nb)
	Send IP datagram.
int	NutIpRouteAdd (uint32_t ip, uint32_t mask, uint32_t gate, NUTDEVICE *dev)
	Add a new entry to the IP routing table.
int	NutIpRouteDelAll (NUTDEVICE *dev)
	Delete all route table entries for the given device.
int	NutIpRouteDel (uint32_t ip, uint32_t mask, uint32_t gate, NUTDEVICE *dev)
	Delete the specified route table entry.
RTENTRY *	NutIpRouteList (int *numEntries)
	Return an array of RTENTRY structures which contain all the current route table entries.
NUTDEVICE *	NutIpRouteQuery (uint32_t ip, uint32_t *gate)
	Find a device associated with a particular IP route.
Variables
int(*	ip_demux )(NUTDEVICE , NETBUF )
	Pointer to an optional demultiplexer.
RTENTRY *	rteList

Detailed Description

RFC 791 Internet protocol version 4.

Internet Protocol checksum and related support.

Before using IP based protocols, you must have registered a network device driver like PPP or one of the supported Ethernet controller drivers.

You must also have configured the IP network interface with NutDhcpIfConfig() or NutNetIfConfig().

Typical applications do not use the IP layer directly, but call the UDP Socket API or the TCP Socket API. A Raw IP API is currently not supported.

Todo:: Configurable checksum calculation for incoming datagrams.

Define Documentation

#define SIOCSIFMTU 0x1001

Set maximum transfer unit.

#define SIOCGIFMTU 0x1002

Get maximum transfer unit.

#define SIOCSIFFLAGS 0x1003

Set interface flags.

Referenced by NutNetIfConfig2().

#define SIOCGIFFLAGS 0x1004

Get interface flags.

Referenced by NutNetIfConfig2().

#define SIOCSIFADDR 0x1005

Set interface address.

Referenced by NutNetIfConfig2().

#define SIOCGIFADDR 0x1006

Get interface address.

#define SIOCADDMULTI 0x1007

Add multicast address.

Referenced by NutNetIfAddMcastAddr().

#define SIOCDELMULTI 0x1008

Delete multicast address.

Referenced by NutNetIfDelMcastAddr().

#define NUT_PERFMON_ADD	(	s,
		a
	)

Referenced by DmOutput(), and NicRxLanc().

#define NUT_PERFMON_INC ( s )

Referenced by DmOutput(), NicRxLanc(), and NutEtherOutput().

#define IP_IS_MULTICAST ( _a ) ((ntohl(_a) & 0xF0000000U) == 0xE0000000U)

Referenced by NutIpOutput(), and NutIpRouteQuery().

#define IPVERSION 4

IP protocol version.

Referenced by NutIpInput().

#define IP_DF 0x4000

Don't fragment flag.

#define IP_MF 0x2000

More fragments flag.

Referenced by NutIpInput().

#define IP_OFFMASK 0x1fff

Mask for fragmenting bits.

Referenced by NutIpInput().

#define IPOPT_EOL 0

End of option list.

#define IPOPT_NOP 1

No operation.

#define IPOPT_RR 7

Record packet route.

#define IPOPT_TS 68

Timestamp.

#define IPOPT_SECURITY 130

Provide s,c,h,tcc.

#define IPOPT_LSRR 131

Loose source route.

#define IPOPT_SATID 136

Satnet id.

#define IPOPT_SSRR 137

Strict source route.

#define IPOPT_OPTVAL 0

Option identifier offset.

#define IPOPT_OLEN 1

Option length offset.

#define IPOPT_OFFSET 2

Offset within option.

#define IPOPT_MINOFF 4

Minimum offset within option.

#define MAXTTL 255

Maximum time to live (seconds).

#define IPDEFTTL 64

Default time to live.

#define IPFRAGTTL 60

Time to live for fragments.

#define IPTTLDEC 1

Subtracted from time to live when forwarding.

Typedef Documentation

typedef struct _MCASTENTRY MCASTENTRY

Multicast address entry type.

typedef struct ifnet IFNET

Network interface type.

typedef struct ip IPHDR

Internet header type.

typedef struct ip_opt IPHDR_OPT

typedef struct _INET_PROTOCOLS INET_PROTOCOLS

Linked list of registered Internet protocols.

Function Documentation

int NutNetIfSetup	(	NUTDEVICE *	dev,
		uint32_t	ip_addr,
		uint32_t	ip_mask,
		uint32_t	gateway
	)

Network interface setup.

Parameters:

dev	Identifies the network device to setup.
ip_addr	Specified IP address in network byte order.
ip_mask	Specified IP network mask in network byte order.
gateway	Optional default gateway.

Returns:: 0 on success, -1 otherwise.

Note:: Typical applications do not use this function, but call NutDhcpIfConfig() or NutNetIfConfig().

References _CONFNET::cd_name, _CONFNET::cdn_gateway, _CONFNET::cdn_ip_addr, _CONFNET::cdn_ip_mask, _CONFNET::cdn_mac, confnet, _NUTDEVICE::dev_icb, _NUTDEVICE::dev_name, ETHER_IS_BROADCAST, ETHER_IS_ZERO, ifnet::if_local_ip, ifnet::if_mac, ifnet::if_mask, memcpy(), NutIpRouteAdd(), and NutNetSaveConfig().

Referenced by NutDhcpIfConfig(), and NutNetIfConfig2().

Here is the call graph for this function:

int NutNetIfConfig	(	const char *	name,
		void *	params,
		uint32_t	ip_addr,
		uint32_t	ip_mask
	)

Configure a network interface.

Devices must have been registered by NutRegisterDevice() before calling this function.

For Ethernet devices applications may alternatively call NutDhcpIfConfig(), which allows automatic configuration by DHCP or the so called ARP method.

Parameters:

name	Name of the device to configure.
params	Pointer to interface specific parameters. For Ethernet interfaces this parameter may be a pointer to a buffer containing the 6 byte long MAC address. This will override the MAC address stored in the non-volatile configuration memory. If this memory is uninitialized or not available, the MAC address must be specified. For PPP interfaces this parameter is ignored and should be set to zero.
ip_addr	Specified IP address in network byte order. This must be a unique address within the Internet. If you do not directly communicate with other Internet hosts, you can use a locally assigned address. With PPP interfaces this may be set to 0.0.0.0, in which case the remote peer will be queried for an IP address.
ip_mask	Specified IP network mask in network byte order. Typical Ethernet networks use 255.255.255.0, which allows up to 254 hosts. For PPP interfaces 255.255.255.255 is the default.

Returns:: 0 on success, -1 otherwise.

Note:: The whole interface configuration has become a mess over the years and need a major redesign.

References NutNetIfConfig2().

Referenced by main().

Here is the call graph for this function:

int NutNetIfConfig2	(	const char *	name,
		void *	params,
		uint32_t	ip_addr,
		uint32_t	ip_mask,
		uint32_t	gateway
	)

Configure a network interface including the default gateway.

Devices must have been registered by NutRegisterDevice() before calling this function.

For Ethernet devices applications may alternatively call NutDhcpIfConfig(), which allows automatic configuration by DHCP or the so called ARP method.

Parameters:

name	Name of the device to configure.
params	Pointer to interface specific parameters.
ip_addr	Specified IP address in network byte order. This must be a unique address within the Internet. If you do not directly communicate with other Internet hosts, you can use a locally assigned address. With PPP interfaces this may be set to 0.0.0.0, in which case the remote peer will be queried for an IP address.
ip_mask	Specified IP network mask in network byte order. Typical Ethernet networks use 255.255.255.0, which allows up to 254 hosts. For PPP interfaces 255.255.255.255 is the default.
gateway	Specified IP address of gateway or next router in LAN.

Returns:: 0 on success, -1 otherwise.

Note:: I do not like this function, because setting a gateway should be handled by NutIpRouteAdd(). It's not yet deprecated, but I recommend not to use it in application code.

References _ioctl(), _PPPDCB::dcb_fd, _PPPDCB::dcb_ip_mask, _PPPDCB::dcb_ipcp_state, _PPPDCB::dcb_local_ip, _PPPDCB::dcb_remote_ip, _PPPDCB::dcb_state_chg, _NUTDEVICE::dev_dcb, _NUTDEVICE::dev_icb, _NUTDEVICE::dev_ioctl, _NUTDEVICE::dev_type, HDLC_SETIFNET, ifnet::if_mac, ifnet::if_type, IFF_UP, IFT_ETHER, IFT_PPP, IFTYP_NET, memcpy(), NutDeviceLookup(), NutEventBroadcast(), NutEventWait(), NutNetIfSetup(), PPPS_OPENED, SIOCGIFFLAGS, SIOCSIFADDR, and SIOCSIFFLAGS.

Referenced by NutDhcpIfConfig(), and NutNetIfConfig().

Here is the call graph for this function:

int NutNetIfAddMcastAddr	(	const char *	name,
		uint32_t	ip_addr
	)

References _NUTDEVICE::dev_icb, _NUTDEVICE::dev_ioctl, _NUTDEVICE::dev_type, ifnet::if_type, IFT_ETHER, IFTYP_NET, INADDR_ALLHOSTS_GROUP, NutDeviceLookup(), NutIgmpJoinGroup(), rc, and SIOCADDMULTI.

Referenced by main(), and upnp_Init().

Here is the call graph for this function:

int NutNetIfDelMcastAddr	(	const char *	name,
		uint32_t	ip_addr
	)

References _NUTDEVICE::dev_icb, _NUTDEVICE::dev_ioctl, _NUTDEVICE::dev_type, ifnet::if_type, IFT_ETHER, IFTYP_NET, INADDR_ALLHOSTS_GROUP, NutDeviceLookup(), NutIgmpLeaveGroup(), rc, and SIOCDELMULTI.

Here is the call graph for this function:

uint32_t inet_addr ( const char * str )

Convert decimal dotted ASCII representation into numeric IP address.

Parameters:

str	String containing the ASCII representation.

Returns:: IP address in network byte order.

Referenced by main(), NutNetLoadConfig(), and resolve().

char* inet_ntoa ( uint32_t addr )

Convert numeric IP address into decimal dotted ASCII representation.

Note:: This function is not thread safe. Each subsequent call will destroy the previous result. Applications should locally store the result before calling the function again or allowing other threads to call it.

Parameters:

addr	IP address in network byte order.

Returns:: Pointer to a static buffer containing the ASCII representation.

Referenced by DhcpStateDebug(), main(), NutArpCacheQuery(), NutArpCacheUpdate(), NutDhcpIfConfig(), NutDumpIpcpOption(), NutDumpSocketList(), print_udp_icmp_error(), SSDPTask(), StreamInfo(), and syslog_header().

char* inet_mtoa ( uint8_t * mac )

Convert numeric MAC address array into double dotted ASCII representation.

Note:: This function is not thread safe. Each subsequent call will destroy the previous result. Applications should locally store the result before calling the function again or allowing other threads to call it.

Parameters:

mac	Pointer to MAC address array.

Returns:: Pointer to a static buffer containing the ASCII representation.

uint16_t NutIpChkSumPartial	(	uint16_t	ics,
		const void *	buf,
		int	len
	)

Calculate a partial IP checksum of a buffer.

The caller must create the one's complement of the final result.

Parameters:

ics	Initial checksum from previous parts.
buf	Pointer to the buffer.
len	Number of bytes in the buffer.

Returns:: Partial checksum in network byte order.

Referenced by NutIcmpOutput(), NutIpChkSum(), NutIpPseudoChkSumPartial(), NutTcpOutput(), and NutUdpOutput().

uint16_t NutIpChkSum	(	uint16_t	ics,
		const void *	buf,
		int	len
	)

Calculates an the final IP checksum over a block of data.

Unlike the partial checksum in NutIpChkSumPartial(), this function takes the one's complement of the final result, thus making it the full checksum.

References NutIpChkSumPartial().

Referenced by NutIcmpOutput(), NutIgmpOutput(), NutIpOutput(), NutTcpOutput(), NutTcpReject(), and NutUdpOutput().

Here is the call graph for this function:

uint32_t NutIpPseudoChkSumPartial	(	uint32_t	src_addr,
		uint32_t	dest_addr,
		uint8_t	protocol,
		int	len
	)

Calculates the partial IP pseudo checksum.

References NutIpChkSumPartial(), pseudo_hdr::ph_dest_addr, pseudo_hdr::ph_len, pseudo_hdr::ph_protocol, pseudo_hdr::ph_src_addr, and pseudo_hdr::ph_zero.

Referenced by NutTcpOutput(), NutTcpReject(), and NutUdpOutput().

Here is the call graph for this function:

int NutRegisterIpHandler	(	uint8_t	prot,
		int()(NUTDEVICE , NETBUF *)	hdlr
	)

Register an additional Ethernet protocol handler.

The specified mask will be applied on the type field of incoming frames before compared with the type that had been specified for the handler. If more than one handler is registered for an incoming Ethernet frame, the handler being registered last is called first.

Each handler should return 0 if it processed the frame, in which case it is also assumed, that the handler releases the memory allocated for the NETBUF. Otherwise the handler should return -1, in which case the frame is passed to the next handler that fits.

The protocol types ETHERTYPE_IP and ETHERTYPE_ARP are pre-registered by default and processed by internal handlers after all registered handlers for that frame rejected processing. This allows to install filters on the Ethernet level.

Parameters:

type	Ethernet protocol type processed by this handler.
mask	Ethernet protocol type mask.
hdlr	Pointer to the protocol handler function. If NULL, the handler will be temporarily disabled.

Returns:: 0 on success, -1 otherwise.

References calloc, _INET_PROTOCOLS::inet_input, _INET_PROTOCOLS::inet_next, _INET_PROTOCOLS::inet_prot, ip_demux, and NULL.

Referenced by main(), NutTcpCreateSocket(), and NutUdpCreateSocket().

void NutIpSetInputFilter ( NutIpFilterFunc callbackFunc )

Set filter function for incoming IP datagrams.

The callbackFunc is called by the IP layer on every incoming IP datagram. Thus it must not block. The implementer returns 0 for allow, -1 for deny.

It is recommended to set the filer after DHCP has done its thing, just in case your DHCP server is on a different subnet for example.

Parameters:

callbackFunc Pointer to callback function to filter IP packets. Set to 0 to disable the filter again.

void NutIpInput	(	NUTDEVICE *	dev,
		NETBUF *	nb
	)

Process incoming IP datagrams.

References _NUTDEVICE::dev_icb, htons, ICMP_UNREACH, ICMP_UNREACH_PROTOCOL, ifnet::if_local_ip, ifnet::if_mask, ifnet::if_mcast, IN_MULTICAST, INADDR_BROADCAST, ip_demux, ip::ip_dst, ip::ip_hl, ip::ip_len, IP_MF, ip::ip_off, IP_OFFMASK, ip::ip_p, ip::ip_src, ip::ip_v, IPPROTO_ICMP, IPPROTO_IGMP, IPVERSION, _MCASTENTRY::mca_ip, _MCASTENTRY::mca_next, _NETBUF::nb_flags, _NETBUF::nb_nw, _NETBUF::nb_tp, NBAF_UNICAST, ntohs, NULL, NutIcmpInput(), NutIcmpResponse(), NutIgmpInput(), NutNetBufFree(), _NBDATA::sz, and _NBDATA::vp.

Referenced by NutEtherInput(), and NutPppInput().

Here is the call graph for this function:

int NutIpOutput	(	uint8_t	proto,
		uint32_t	dest,
		NETBUF *	nb
	)

Send IP datagram.

Route an IP datagram to the proper interface.

The function will not return until the data has been stored in the network device hardware for transmission. If the device is not ready for transmitting a new packet, the calling thread will be suspended until the device becomes ready again. If the hardware address of the target host needs to be resolved the function will be suspended too.

Parameters:

proto	Protocol type.
dest	Destination IP address. The function will determine the proper network interface by checking the routing table. It will also perform any necessary hardware address resolution.
nb	Network buffer structure containing the datagram. This buffer will be released if the function returns an error.

Returns:: 0 on success, -1 otherwise.

Bug:: Broadcasts to multiple network devices will fail after the first device returns an error.

References _NUTDEVICE::dev_icb, _NUTDEVICE::dev_next, _NUTDEVICE::dev_type, ETHERTYPE_IP, htonl, htons, ifnet::if_local_ip, ifnet::if_mask, ifnet::if_output, ifnet::if_pkt_id, ifnet::if_type, IFT_ETHER, IFT_PPP, IFTYP_NET, ip_opt::ip_dst, ip_opt::ip_hl, ip_opt::ip_id, IP_IS_MULTICAST, ip_opt::ip_len, ip_opt::ip_off, ip_opt::ip_option, ip_opt::ip_p, ip_opt::ip_src, ip_opt::ip_sum, ip_opt::ip_tos, ip_opt::ip_ttl, ip_opt::ip_v, IPPROTO_IGMP, memset(), _NETBUF::nb_ap, _NETBUF::nb_nw, _NETBUF::nb_tp, NBAF_NETWORK, NutArpCacheQuery(), nutDeviceList, NutIpChkSum(), NutIpRouteQuery(), NutNetBufAlloc(), NutNetBufClonePart(), NutNetBufFree(), PPP_IP, rc, _NBDATA::sz, and _NBDATA::vp.

Referenced by NutIcmpOutput(), NutIgmpOutput(), NutTcpOutput(), NutTcpReject(), NutTcpStateRetranTimeout(), and NutUdpOutput().

Here is the call graph for this function:

int NutIpRouteAdd	(	uint32_t	ip,
		uint32_t	mask,
		uint32_t	gate,
		NUTDEVICE *	dev
	)

Add a new entry to the IP routing table.

Note, that there is currently no support for detecting duplicates. Anyway, newer entries will be found first, because they are inserted in front of older entries. However, this works only for equal masks, i.e. new network routes will never overwrite old host routes.

Parameters:

ip	Network or host IP address to be routed. Set 0 for default route.
mask	Mask for this entry. -1 for host routes, 0 for default or net mask for net routes.
gate	Route through this gateway, otherwise 0.
dev	Network interface to use.

Returns:: 0 on success, -1 otherwise.

References malloc(), NULL, rc, _RTENTRY::rt_dev, _RTENTRY::rt_gateway, _RTENTRY::rt_ip, _RTENTRY::rt_mask, _RTENTRY::rt_next, and rteList.

Referenced by main(), and NutNetIfSetup().

Here is the call graph for this function:

int NutIpRouteDelAll ( NUTDEVICE * dev )

Delete all route table entries for the given device.

Parameters:

dev	Pointer to the device. If NULL, it deletes all route table entries.

Returns:: 0 on success, -1 otherwise.

References free(), _RTENTRY::rt_dev, _RTENTRY::rt_next, and rteList.

Here is the call graph for this function:

int NutIpRouteDel	(	uint32_t	ip,
		uint32_t	mask,
		uint32_t	gate,
		NUTDEVICE *	dev
	)

Delete the specified route table entry.

All fields must exactly match an existing entry.

Parameters:

ip	Network or host IP address of the route entry.
mask	Mask for this entry. -1 for host routes, 0 for default or net mask for net routes.
gate	Route through this gateway, 0 for default gate.
dev	Network interface to use.

Returns:: 0 on success, -1 otherwise.

References free(), rc, _RTENTRY::rt_dev, _RTENTRY::rt_gateway, _RTENTRY::rt_ip, _RTENTRY::rt_mask, and _RTENTRY::rt_next.

Here is the call graph for this function:

RTENTRY* NutIpRouteList ( int * numEntries )

Return an array of RTENTRY structures which contain all the current route table entries.

The calling function is responsible for deleting the array.

Parameters:

numEntries Points to an integer, which receives the length of the array.

Returns:: Pointer to the array. Will be NULL in case of an error.

References malloc(), memcpy(), rc, and _RTENTRY::rt_next.

Here is the call graph for this function:

NUTDEVICE* NutIpRouteQuery	(	uint32_t	ip,
		uint32_t *	gate
	)

Find a device associated with a particular IP route.

Gateway routes will be automatically resolved up to four levels of redirection.

Parameters:

ip	IP address to find a route for, given in network byte order.
gate	Points to a buffer which optionally receives the IP address of a gateway. The pointer may be NULL, if the caller is not interested in this information.