tfUseInterfaceScatRecv

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int tfUseInterfaceScatRecv (
ttUserInterface interfaceHandle,
ttDevScatRecvFuncPtr drvScatRecvFuncPtr
);


Function Description

By default the stack expects all data within a frame given by the user device driver recv function to be contiguous. Some device drivers support receiving data within a frame in scattered buffers ("Gather Read"), because it is more efficient. tfUseInterfaceScatRecv() replaces the default device driver recv function added in tfAddInterface() with a driver scattered recv function that is called once per frame, even when the device driver received data is scattered on a given interface ("Gather Read"). tfUseInterfaceScatRecv() must be called prior to calling tfConfigInterface(), and after having called tfAddInterface(), to replace the device driver recv function specified in tfAddInterface(). If tfUseInterfaceScatRecv() has been called successfully, the user needs to call tfRecvScatInterface() instead of tfRecvInterface(). tfRecvScatInterface() will call the modified device driver recv function specified in the tfUseInterfaceScatRecv() call.


Note Note: TM_USE_DRV_ONE_SCAT_RECV must be defined in <trsystem.h>


Parameters

  • interfaceHandle
    The interface handle of the device we wish to receive data from.
  • drvScatRecvFuncPtr
    A function pointer to the device driver's recv function that handles scattered data within a frame in a single call.


Returns

  • TM_ENOERROR
    Success.
  • TM_EINVAL
    devScatRecvFunc is null.
  • TM_EPERM
    The interface has already been opened.


devScatRecvFunc

int devScatRecvFunc(ttUserInterface  interfaceHandle,
                    ttDruBlockPtrPtr uDevBlockPtrPtr,
                    int*             uDevBlockCountPtr,
                    int*             flagPtr);


devScatRecvFunc Parameters

  • interfaceHandle
    The interface handle of the device we wish to receive data from.
  • uDevBlockPtrPtr
    Address of an area where to store an array of user blocks descibing the scattered data (one block per scattered buffer).
  • uDevBlockCountPtr
    Address of an area where to store the number of scattered buffers within a frame.
  • flagPtr
    Address of an area where to store ownership of the scattered buffers that compose the received frame.


Upon return from the device driver scattered recv function, *uDevBlockPtrPtr points to an array of ttDruBlock.

There is one ttDruBlock per scattered buffer in the received frame. Each ttDruBlock element contains a pointer to a user buffer, a pointer to the beginning of the user data in the user buffer, and the user data length in the user buffer.


ttDruBlock Fields

  • druDataPtr
    Points to the beginning of the data.
  • druDataLength
    Indicates the data length.
  • druBufferPtr
    Pointer to be passed to the device driver free function if the user sets the flag to TM_DEV_SCAT_RECV_USER_BUFFER in the driver recv function. (See *flagPtr below.)
  • druStackBufferPtr
    Pointer to a stack pre-allocated user buffer if the user sets the flag to TM_DEV_SCAT_RECV_STACK_BUFFER in the driver recv function. (See *flagPtr below.)


If the device driver scattered recv function sets *flagPtr to TM_DEV_SCAT_RECV_STACK_BUFFER, then druStackBufferPtr should point to a buffer pointed to by the first parameter of either tfGetEthernetBuffer(), or tfGetDriverBuffer(), and the stack will be responsible for freeing that buffer, when the stack is done processing that buffer. If the device driver scattered recv function sets *flagPtr to TM_DEV_SCAT_RECV_USER_BUFFER, then druBufferPtr points to a user allocated buffer. When the stack is done processing that buffer, the stack will call the device driver free function (as set in tfAddInterface()).

The user is responsible for managing the memory containing the array of ttDruBlock. It is guaranteed that when the stack calls the modified driver recv function on an interface, the array of ttDruBlock previously given to the stack by a previous call to the driver recv function on the same interface will not be accessed anymore. So it is safe for the user to re-use the array itself, then. On the other hand, it is only safe to re-use a user allocated buffer after the device driver free function has been called.


Possible *flagPtr Values

  • TM_DEV_SCAT_RECV_STACK_BUFFER
    The scattered buffers used in the frame are pre-allocated stack buffers. The stack will be responsible for freeing these buffers.
  • TM_DEV_SCAT_RECV_USER_BUFFER
    The scattered buffers used in the frame belong to the user. When the stack is done processing a buffer in a received frame, the device driver free function as specified in tfAddInterface() will be called for that buffer.


Table of Contents >> Programmer's Reference