NetIF_GetTxDataAlignPtr

Get an aligned pointer into a transmit application data buffer.

Files

net_if.h/net_if.c

Prototype

          void  *NetIF_GetTxDataAlignPtr(NET_IF_NBR   if_nbr,
                                         void        *p_data,
                                         NET_ERR     *p_err);

Arguments

if_nbr

Network interface number to get a transmit application buffer's aligned data pointer.

p_data

Pointer to transmit application data buffer to get an aligned pointer into (see also Note #2b).

p_err

Pointer to variable that will receive the return error code from this function :

NET_IF_ERR_NONE
NET_IF_ERR_NULL_PTR
NET_IF_ERR_INVALID_IF
NET_IF_ERR_ALIGN_NOT_AVAIL
NET_ERR_INIT_INCOMPLETE
NET_ERR_INVALID_TRANSACTION
NET_ERR_FAULT_LOCK_ACQUIRE

Returned Value

Pointer to aligned transmit application data buffer address, if no errors.

Pointer to NULL, otherwise.

Required Configuration

None.

Notes/Warnings #1

1. Optimal alignment between application data buffers and the network interface's network buffer data areas is not guaranteed, and is possible if, and only if, all of the following conditions are true:

   Network interface's network buffer data areas must be aligned to a multiple of the CPU's data word size.

   Otherwise, a single, fixed alignment between application data buffers and network interface's buffer data areas is not possible.

2. Even when application data buffers and network buffer data areas are aligned in the best case, optimal alignment is not guaranteed for every read/write of data to/from application data buffers and network buffer data areas.

   For any single read/write of data to/from application data buffers and network buffer data areas, optimal alignment occurs if, and only if, all of the following conditions are true:

   Data read/written to/from application data buffers to network buffer data areas must start on addresses with the same relative offset from CPU word-aligned addresses.

   In other words, the modulus of the specific read/write address in the application data buffer with the CPU's data word size must be equal to the modulus of the specific read/write address in the network buffer data area with the CPU's data word size.

   This condition might not be satisfied whenever:

   • Data is read/written to/from fragmented packets
   • Data is not maximally read/written to/from stream-type packets (e.g., TCP data segments)
   • Packets include variable number of header options (e.g., IP options)

   However, even though optimal alignment between application data buffers and network buffer data areas is not guaranteed for every read/write; optimal alignment should not occur more frequently, leading to improved network data throughput.

Notes/Warnings #2

Since the first aligned address in the application data buffer may be 0 to (CPU_CFG_DATA_SIZE-1) bytes after the application data buffer's starting address, the application data buffer should allocate and reserve an additional (CPU_CFG_DATA_SIZE-1) number of bytes.

However, the application data buffer's effective, useable size is still limited to its original declared size (before reserving additional bytes), and should not be increased by the additional, reserved bytes.