Low-overhead UDP Functions

6.1UDP functions

These calls to the UDP layer are provided for systems that do not need the overhead of sockets (see Chapter 5 Sockets). These routines impose a lower demand on CPU and system memory requirements than sockets. However, they do not offer the portability of sockets. Most of these functions are defined in inet\udp.c. The exceptions are documented.

The following sections describe the low-overhead UDP functions. They are as follows:

•udp_alloc() on page 6-2

•udp_close() on page 6-3

•udp_free() on page 6-4

•udp_open() on page 6-5

•udp_send() on page 6-6

•udp_socket() on page 6-7.

6.1.1udp_alloc()

This returns a packet large enough for the UDP data. It works by adding the space needed for UDP, IP, and MAC headers to the datalen passed, and calling pk_alloc(). It also ensures that the FREEQ_RESID resource is locked around the call to pk_alloc().

Syntax

PACKET udp_alloc(int datalen, int optlen)

where:

datalen Is the length of UDP data, not including the UDP header.

optlen Is the length of IP options, if any. This is typically 0.

Return value

Returns one of the following:

PACKET A pointer to a packet buffer.

NULL	If a large-enough packet was not available.

When the packet has been successfully transmitted by the hardware, it must be released by calling udp_free(). This is usually done by the sending interface.

6-2

Copyright © 1998-2001 ARM Limited. All rights reserved.

ARM DUI 0144B

Low-overhead UDP Functions

6.1.2udp_close()

This function must be called by your application when it has finished with a UDP connection and is no longer interested in receiving UDP packets associated with the connection. This function is defined in inet\udp_open.c.

Syntax

void udp_close(UDPCONN con)

where:
con	Is the UDP connection identifier returned by a previous call to
	udp_open().

Return value

None.

ARM DUI 0144B

Copyright © 1998-2001 ARM Limited. All rights reserved.

6-3

Low-overhead UDP Functions

6.1.3udp_free()

This function returns a previously allocated packet to the free pool on the stack. It calls pk_free() and ensures that the FREEQ_RESID resource is locked around the access to the free packet pool.

Syntax

void udp_free(ptr)

where:
ptr	Is a pointer to the netbuf structure previously allocated by
	udp_alloc().

Return value

None.

6-4

Copyright © 1998-2001 ARM Limited. All rights reserved.

ARM DUI 0144B

Low-overhead UDP Functions

6.1.4udp_open()

This function is defined in inet\udp_open.c and creates a structure in the UDP layer to receive, and pass upwards, UDP packets that match the parameters passed. The foreign host, fhost, and port, fport, can be set to 0 as a wild card, which enables the reception of broadcast datagrams.

The callback handler function is called with a pointer to a received datagram and a copy of the data pointer which is passed to udp_open(). This can be any data the programmer requires, such as a pointer to another function, or a control structure to aid in demultiplexing the received UDP packet.

Syntax

UDPCONN udp_open(ip_addr fhost,

	unsigned short fport,
	unsigned short lport,
	int (*handler)(PACKET, void *),
	void *data)
where:
fhost	Is the foreign host from which you will accept data. It must be set to 0 if
	listening for any host.
fport	Is the foreign port number. It must be set to 0 if listening for datagrams
	from any foreign port.
lport	Is the local port on which to receive data.
handler	Is the UDP receive callback function.
data	Is the data that is passed (along with the received UDP datagram) to the
	callback handler.

Return value

Returns one of the following:

ID	A UDP connection identifier if successful. This handle must be passed to
	udp_close() when the connection is no longer required.
NULL	If not successful.

ARM DUI 0144B

Copyright © 1998-2001 ARM Limited. All rights reserved.

6-5