Low Level Processing (NetDoRx)

Callback functions to add custom Ethernet handlers and pass Ethernet frames at the bottom of the TCP/IP stack. More...

Typedefs
typedef int(*	netDoRXFunc) (PoolPtr pp, uint16_t ocount, int if_num)
	Function pointer type for custom network receive handlers.

Functions
netDoRXFunc	SetCustomNetDoRX (netDoRXFunc customFunc)
	Register a custom Ethernet frame handler.
netDoRXFunc	ClearCustomNetDoRX ()
	Remove the currently registered custom Ethernet handler.
int	NetDoRX (PoolPtr pp, uint16_t ocount, int if_num)
	Main entry point for Ethernet frames into the TCP/IP stack.

Variables
netDoRXFunc	CustomNetDoRX
	Global pointer to the currently registered custom receive handler.

Detailed Description

Callback functions to add custom Ethernet handlers and pass Ethernet frames at the bottom of the TCP/IP stack.

#include< netrx.h>

This module provides the infrastructure for inserting custom Ethernet frame handlers into the network receive path. Custom handlers run before the standard TCP/IP processing and can filter, modify, or consume frames.

Common use cases include:

• Custom protocol implementation
• Frame filtering or monitoring
• Network statistics collection
• Protocol bridging or tunneling

Note

Custom handlers require that the system is (re)compiled with the ALLOW_CUSTOM_NET_DO_RX macro defined.

Warning

These functions are for advanced developers only! Code written can affect all receive network processing and must handle frames efficiently to avoid packet loss or network degradation.

Typedef Documentation

netDoRXFunc

typedef int(* netDoRXFunc) (PoolPtr pp, uint16_t ocount, int if_num)

#include <netrx.h>

Function pointer type for custom network receive handlers.

This typedef defines the signature for custom Ethernet frame processing functions. Functions of this type are called for each received Ethernet frame before standard TCP/IP processing occurs.

The handler function should:

• Examine the frame data in the buffer
• Decide whether to process or pass the frame
• Return 1 if the frame was consumed (will be released)
• Return 0 if the frame should continue to standard processing

Parameters

pp	Pointer to PoolBuffer containing the received Ethernet frame. The buffer contains the complete frame including Ethernet header.
ocount	Total number of octets (bytes) in the received frame, including all headers and payload.
if_num	Network interface index that received the frame. Zero-based index identifying which physical interface the frame arrived on.

Returns

Status indicating whether the frame was handled:

• 1: Frame was processed and consumed by the handler. The buffer will be released and no further processing will occur.
• 0: Frame was not processed. Continue with standard TCP/IP stack processing.

Note

The handler must not modify the buffer or its contents unless it returns 1 to indicate it has consumed the frame.

Warning

Performance critical! This function is called for EVERY received frame. Inefficient implementations can cause packet loss and network degradation.

// Example: Custom handler that monitors ARP frames
int MyArpMonitor(PoolPtr pp, uint16_t ocount, int if_num) {
    // Get pointer to Ethernet header
    uint8_t *frame = (uint8_t *)pp->pData;
    
    // Check if this is an ARP frame (EtherType 0x0806)
    if (ocount >= 14 && frame[12] == 0x08 && frame[13] == 0x06) {
        // Log ARP frame (but don't consume it)
        iprintf("ARP frame received on interface %d\r\n", if_num);
    }
    
    // Don't consume - let stack process normally
    return 0;
}

Function Documentation

ClearCustomNetDoRX()

netDoRXFunc ClearCustomNetDoRX ( )

inline

#include <netrx.h>

Remove the currently registered custom Ethernet handler.

Clears the custom Ethernet frame handler by setting it to NULL. After calling this function, all received frames will go directly to standard TCP/IP processing without any custom pre-processing.

This is a convenience function equivalent to calling SetCustomNetDoRX(NULL).

Returns

Pointer to the previously registered custom handler, or NULL if no handler was registered. The returned pointer can be saved to restore the handler later if needed.

Note

This function is thread-safe and can be called at any time.

// Example: Temporarily disabling a handler
netDoRXFunc savedHandler = ClearCustomNetDoRX();
 
// ... do something without custom handler ...
 
// Restore the handler
if (savedHandler != NULL) {
    SetCustomNetDoRX(savedHandler);
}

NetDoRX()

int NetDoRX	(	PoolPtr	pp,
		uint16_t	ocount,
		int	if_num )

#include <netrx.h>

Main entry point for Ethernet frames into the TCP/IP stack.

This function is the primary entry point for all received Ethernet frames into the NetBurner TCP/IP stack. It is called by the network driver when a frame has been received and is ready for processing.

The function performs the following operations:

1. If a custom handler is registered, calls it first
2. If custom handler returns 1, releases the buffer and returns
3. Otherwise, processes the frame through standard TCP/IP layers:
   • Ethernet layer processing
   • IP layer processing (if IP frame)
   • Transport layer processing (TCP/UDP/ICMP)
   • Application layer delivery

Parameters

pp	Pointer to PoolBuffer containing the complete Ethernet frame. The buffer includes the Ethernet header and all subsequent data. The buffer is released by this function unless an error occurs.
ocount	Number of octets (bytes) in the Ethernet frame, including the Ethernet header. This is the total frame size as received from the network interface.
if_num	Zero-based index of the network interface that received the frame. This identifies which physical network interface (Ethernet port) the frame arrived on. Used for multi-interface routing decisions.

Returns

The number of system timer ticks to wait before this function should be called again for additional processing. A return value of 0 indicates immediate readiness for more frames. This is primarily used internally by the network driver.

Note

This function is typically called only by network driver code and should not be called directly by application code.

The PoolPtr buffer is managed internally and will be released after processing unless an error occurs.

Warning

Do not call this function from application code unless implementing a custom network driver or performing specialized network operations.

SetCustomNetDoRX()

netDoRXFunc SetCustomNetDoRX ( netDoRXFunc customFunc )

inline

#include <netrx.h>

Register a custom Ethernet frame handler.

Installs a custom handler function that will be called for every received Ethernet frame before standard TCP/IP processing. Only one custom handler can be active at a time; calling this function replaces any previously registered handler.

The custom handler is invoked in the network receive interrupt context and should:

• Execute quickly to avoid blocking other network processing
• Be thread-safe if accessing shared resources
• Return 1 only if completely handling/consuming the frame
• Return 0 to pass the frame to standard processing

Parameters

customFunc

Pointer to the custom netDoRXFunc handler to register. Pass NULL to clear the custom handler.

Returns

Pointer to the previously registered custom handler, or NULL if no handler was previously registered. This allows chaining handlers or restoring the previous handler later.

Note

This function is thread-safe and can be called at any time.

Warning

The handler runs in interrupt context with network interrupts enabled. It must be efficient and non-blocking.

// Example: Installing and later restoring a handler
int MyHandler(PoolPtr pp, uint16_t ocount, int if_num) {
    // Process frame...
    return 0;
}
 
void InstallHandler() {
    // Save previous handler
    netDoRXFunc oldHandler = SetCustomNetDoRX(MyHandler);
    
    // ... later, restore previous handler ...
    SetCustomNetDoRX(oldHandler);
}

Variable Documentation

CustomNetDoRX

netDoRXFunc CustomNetDoRX

extern

#include <netrx.h>

Global pointer to the currently registered custom receive handler.

This external variable holds the function pointer to the active custom network receive handler. If NULL, no custom handler is registered and all frames go directly to standard TCP/IP processing.

Note

Do not modify this variable directly. Use SetCustomNetDoRX() and ClearCustomNetDoRX() for proper handler registration.