TCP/IP API Functions

3.1.2dprintf() and initmsg()

Both dprintf() and initmsg() are functionally the same as printf(). Both are called by the stack code to inform the programmer or end user of system status. The initmsg() function prints normal status messages at initialization time and dprintf() prints error and warning messages during runtime.

Syntax

void dprintf(char *fmt, …)

void initmsg(char *fmt, …)

where:

fmt	Is a format string like printf().

…Is an argument list, as described by fmt.

Return value

None.

Usage

You can either define these functions to use printf() in ipport.h or you can write your own implementation. See the sample code in \misclib\ttyio.c for a sample implementation.

The ttyio.c implementation of dprintf() uses of the function dputchar() to perform its output. By default, dputchar() is implemented as part of the UART driver, to allow debug output to be sent to a serial terminal. If you have other debug channels, for example a video card, then debug may be redirected by recoding dputchar().

See also the detailed description in Debugging aids on page 2-6.

3-4

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

ARM DUI 0144B

TCP/IP API Functions

3.1.3dtrap()

This function can enter a debugger when it is called.

Syntax

void dtrap(void)

Return value

None.

Usage

See the detailed description in Debugging aids on page 2-6.

ARM DUI 0144B

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

3-5

TCP/IP API Functions

3.1.4ENTER_CRIT_SECTION() and EXIT_CRIT_SECTION()

These two functions protect a sequence of code that must be allowed to complete without interruption (see Implementing pre-emption and protection on page 2-16).

Syntax

void ENTER_CRIT_SECTION(void *ptr)

void EXIT_CRIT_SECTION(void *ptr)

where:
ptr	Refers to a memory location specific to this critical section. The ptr
	parameter might be used by your function to identify which critical
	section is being entered and released, and to confirm that nested critical
	sections are exited in the correct order.

Return value

None.

Usage

Typically these functions disable and re-enable interrupts. On UNIX-like systems, they can be mapped to the spl() primitive. Examples for the Integrator/AP are provided in the sample code.

Refer to The critical section method on page 2-16 for more information on critical sections.

3-6

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

ARM DUI 0144B

TCP/IP API Functions

3.1.5LOCK_NET_RESOURCE() and UNLOCK_NET_RESOURCE()

These two functions are used by the system to preserve mutual exclusion on important data structures in much the same way as the ENTER_CRIT_SECTION() and EXIT_CRIT_SECTION() functions described above. Resource locking is required by some RTOS implementations in order to guarantee minimum latency for time critical tasks. If you are porting ARM TCP/IP to such an environment, you must map

LOCK_NET_RESOURCE() and UNLOCK_NET_RESOURCE() onto the appropriate calls for your RTOS.

Syntax

void LOCK_NET_RESOURCE(int resourceid)

void UNLOCK_NET_RESOURCE(int resourceid)

where:

resourceid Is the system resource identifier to be locked. Three such identifiers are required by the TCP/IP stack:

NET_RESID	Protects the majority of the data structures
	on the TCP/IP stack.
RXQ_RESID	Protects the received packet queue data
	structure.
FREEQ_RESID	Protects the free packet queue data structure.

These must be #defined in ipport.h and mapped onto suitable resource identifiers for your operating system.

Return value

None.

Usage

The LOCK_NET_RESOURCE() function must block until the resource identified by resourceid is available. When the resource lock is available, LOCK_NET_RESOURCE() must lock it and return. While waiting for the lock to become available, the task scheduler must be allowed to run other tasks.

Testing and setting the lock must be an atomic operation to prevent two tasks from believing that they have both locked the same resource. If you are using resource locking implemented within an RTOS, this has already been done for you. Otherwise, this is usually implemented by turning off all interrupts while the test and set operations are performed.

ARM DUI 0144B

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

3-7