@CHIP-RTOS - Data Structures used in TCP/IP Device Driver API

Data Structures

1. Byte alignment is required within all data structures used within the API.
2. The phrase "network byte order" means big endian (like Motorola machines, unlike Intel).

• TCP/IP API Data Structures
• IP Security Data Structures

This type references a buffer private type used internally by the TCP/IP stack. It is defined as:

     typedef void far * DevUserBuffer ;

Related Topics

DevUserBufferHandle type

Dev_Get_Buffer() API - Get a buffer from TCP/IP stack

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

This type references a buffer handle private type used internally by the TCP/IP stack. It is defined as:

     typedef DevUserBuffer far * DevUserBufferHandle ;

Note:   This actually is a pointer to a pointer to a receiver buffer.   An alternative equivalent definition would have been:

     typedef void far * far * DevUserBufferHandle ;

Related Topics

DevUserBuffer type - Device buffer handle (private)

Dev_Get_Buffer() API - Get a buffer from TCP/IP stack

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

typedef struct tag_DevUserDriver
{
    int                    DevIndex;        // Internal device index, filled by @CHIP-RTOS
    char far *             DevName;         // Unique device name, max. 13 chars  + 0
    unsigned long          IpAddr;          // IP address
    unsigned long          Netmask;         // Netmask
    DevUserIfaceHandle     IfaceHandle;     // handle to identify the interface internal
    DevUserLinkLayer       LinkLayerHandle; // handle to identify the link layer internal
    unsigned char          iface_type,      // Type of the device driver:
    unsigned char           use_dhcp;       // Boolean, set to 1 for DHCP
    UserEthDhcp_Entry far * Dhcp_Data;      // Pointer to DHCP data
    void far *              PPPLinkNotify;
    PPP_Option  far *       PPPoptions;
    union {
       unsigned long    peerIPv4 ;
   } u ;

    void  far *             DevOpen;        // Driver Open/initialize function,
    void  far *             DevClose;       // Driver Close function,
    void  far *             DevSend;        // Driver send function
    void  far *             DevRecv;        // Driver recv function
    void  far *             DevGetPhysAddr; // Ethernet driver only, returns MAC address,
    void  far *             DevFreeRecv;    // Free own allocated buffer,
    void  far *             DevIoctl;       // Driver special function, e.g. informs about ip config update
    int   far *             ErrorCode;      // Contains error code, if driver install
    void  far *             Reserved4;      // reserved for future extensions
    void  far *             Reserved5;
    void  far *             Reserved6;

} DevUserDriver;

Comments

The DevUserDriver is the main structure for installing your own device drivers/interfaces for the TCP/IP stack of the @CHIP-RTOS.

This structure must be prepared by the user prior to calling the Dev_Open_Interface() API.   When DHCP is used to configure an Ethernet interface, after a successful call to Dev_Open_Interface() this same data structure will be passed to the Dev_Wait_DHCP_Complete() API to pick up the IP address and network mask.

Several device driver callback functions are specified by the user in this data structure.   Many of these callbacks may be set to NULL when no callback is desired for the respective action.   Only the DevSend and DevRecv vectors are mandatory for all drivers.   And a DevGetPhysAddr callback is required for Ethernet device drivers.

Each callback must be declared huge so that your program's Data Segment will be referenced by the CPU's DS register.

For future source code compatility, the reserved fields in this data structure should not be referenced by name in your program due to that the names of these members may change in future versions of this API.

The remaining structure members are documented here.   The structure contains both input parameters to be set by the caller, and output values set by the Dev_Open_Interface() API. The structure members which the caller must set are highlighted in bold print below.

DevIndex

Output Parameter: Internal device index set by Dev_Open_Interface() API.

DevName

Unique device name, maxium 13 characters plus one zero byte at end for the ASCII string terminator.

IpAddr

IPv4 address for this device in network byte order.   When use_dhcp member is set to 1 this is an output parameter set by the Dev_Wait_DHCP_Complete().   Otherwise this must be set by caller prior to calling the Dev_Open_Interface() API.

Netmask

Netmask for this device in network byte oder.  When use_dhcp member is set to 1 this is an output parameter set by the Dev_Wait_DHCP_Complete().   Otherwise this must be set by caller prior to calling the Dev_Open_Interface() API.

IfaceHandle

Input/Output parameter:   Handle to identify the link layer internally.   At the first Dev_Open_Interface() call for a device, this member must be set to NULL by the caller.   On success, the Dev_Open_Interface() API will output the new device handle here.

If the interface is later restarted by calling Dev_Close_Interface() followed by Dev_Open_Interface() again (e.g. for changing IP configuration), this member must contain at the Dev_Open_Interface() call the valid IfaceHandle handle output by the first Dev_Open_Interface() call made for this device.

LinkLayerHandle

Output parameter:   Handle for internal use set here by the Dev_Open_Interface() API during the device add step and there after of use to neither the application nor the system (provisional).

iface_type

Device driver type:



• 0 = Unknown user specific device
  
• 1 = DEV_ETHERNET : Device is an Ethernet controller
  
• 2 = DEV_PPP_SERVER : Use PPP protocol as a server
  
• 3 = DEV_PPP_CLIENT : Use PPP protocol as a client
  
• 4 = Use SLIP protocol (currently not supported)
  
• 5 = DEV_PPPoE_CLIENT : Use PPP protocol over Ethernet as a client.
  
• 6 = DEV_IP_TUNNEL : Device is an IP tunnel, such as used by OpenVPN TUN device mode.
  

The DEV_ADD_ONLY flag can be OR'ed into these driver types to tell the Dev_Open_Interface() API that you want the device to be added but not configured.

use_dhcp

Set to 1 if you want to use IP configuration from a DHCP server.   This applies to iface_type DEV_ETHERNET

Dhcp_Data

Output parameter:   A pointer to DHCP storage data is set here by the Dev_Wait_DHCP_Complete() API on success.   Calling Dev_Wait_DHCP_Complete() only makes sense when the user had set use_dhcp member to 1 before the call to Dev_Open_Interface().   In this case the Dev_Open_Interface() will have set this member to NULL.

See UserEthDhcp_Entry.

PPPLinkNotify

This member is ignored unless the iface_type is set to 2 or 3 (PPP server or client).     This is a pointer to a user provided "link notify" callback function, which is called by the PPP layer to inform the user about the current PPP device status.  Set this pointer to NULL if a link notify callback from the the PPP layer is not required by your driver.

The callback function should have the form:

void huge PPPnotify(DevUserIfaceHandle ifaceHandle, int flags);


The function is called with the interface handle and a set of flags.   The flags consists of one or more of the following bits OR'ed together:


0x0002:   PPP device is ready to accept data from the user
0x0008:   Close procedure started
0x0010:   PPP device has closed
0x0020:   LCP layer is up
0x0040:   PAP is up
0x0080:   CHAP is up

PPPoptions

Pointer to the first PPP option (struct PPP_Option) of a user provided PPP option array.   These options will be set inside the Dev_Open_Interface() call.   If the setting of the option failed, the Dev_Open_Interface exits with error 222 or 242.

As an end marker, the element protocol_level of the last option of the array must be 0.

Set this pointer to null, if you have no PPP options.

DevOpen

Driver Open/initialize function vector provided by the user.   This callback is optional (pass a NULL pointer here if not used).

This callback function should satisfy the following prototype:

     int huge myDevOpen( DevUserIfaceHandle ifaceHandle);

where the ifaceHandle is the same as that output by the Dev_Open_Interface() API in the IfaceHandle field of this structure.

DevClose

Driver close function vector provided by the user.   This callback is optional (pass a NULL pointer if not used).

This callback function should satisfy the following prototype:

     int huge myDevClose( DevUserIfaceHandle ifaceHandle);

DevSend

This send callback function, whose address must be provided here by the user, is required by all drivers.

This callback function must satisfy the following prototype:

     int huge myDevSend( DevUserIfaceHandle ifaceHandle,
                      char far * dataPtr,
                      int dataLength,
                      int flag );

Go here for an example.

DevRecv

This receive callback function, whose address must be provided here by the user, is required by all drivers.

This callback function must satisfy the following prototype:

     int huge myDevRecv( DevUserIfaceHandle ifaceHandle,
                      char far * far * dataPtrPtr,
                      int far * dataLength,
                      DevUserBufferHandle bufferHandle );

Go here for examples.

DevGetPhysAddr

This callback function is required only for Ethernet devices.   This vector should be set to NULL for other type devices.

The function must satisfy the following prototype:

     int huge myDevGetPhysAddr( DevUserIfaceHandle ifaceHandle,
                              unsigned char far * physicalAddress) ;

The Ethernet adaptor's 6 byte MAC address must be copied out to the provided buffer space at physicalAddress.

Go here for an example.

DevFreeRecv

This optional callback function frees receive buffers allocated by the application.   This vector may be set to NULL if this callback is not required.

This callback function must satisfy the following prototype:

     int huge myDevFreeRecv( DevUserIfaceHandle ifaceHandle,
                           char far *dataPtr);

Go here for an example.

DevIoctl

Vector to callback function invoked for various I/O control actions.   This can be set to NULL if no control callback is desired.

This callback function must satisfy the following prototype:

     int huge myDevIoctl( DevUserIfaceHandle ifaceHandle,
                        int flag,
                        void far * optionPtr,
                        int optionLen) ;

See myDevIoctl() example.

ErrorCode

Pointer to output parameter:   The user must place a pointer here to an integer which will receive an error code in the event that the Dev_Open_Interface() API fails at the device add step.

(Note:   This output parameter has been made optional on SC1x3/SC2x @CHIP-RTOS-x86 release V1.35 and beyond.   For current @CHIP-RTOS-x86 version you may set this parameter to NULL if the return value from Dev_Open_Interface() is sufficient for your API failure detection purposes.)

Related Topics

API function Dev_Open_Interface() API Open/install a user TCP/IP device driver/interface

DevUserIfaceHandle type - IfaceHandle structure member

DevUserLinkLayer type - LinkLayerHandle structure member

UserEthDhcp_Entry type - Dhcp_Data structure member

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

Handle type for identification of a TCP/IP device interface.   This can be either one of the built-in drivers or a driver installed by user.

This handle is required at several Device Driver API functions.   The data referenced by this handle is private to the @CHIP-RTOS-x86 TCP/IP stack.

A handle of this type is returned in the IfaceHandle member of the DevUserDriver structure used in the Dev_Open_Interface() API.

typedef void far *  DevUserIfaceHandle;   // handle type, to identify a user interface

Comments

The data referenced by this handle is private and internal to the @CHIP-RTOS TCP/IP stack.

Related Topics

Dev_Open_Interface() API Open/install a user TCP/IP device driver/interface

Dev_Get_Handle_By_Name() API Get TCP/IP device driver/interface handle by name.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

typedef struct tag_DevIpv4IfaceCfg
{
  DevUserIfaceHandle     IfaceHandle;     // handle to identify the interface internal
  unsigned long          IpAddr;          //IP address
  unsigned long          Netmask;         //Netmask
  int                    flags;
  int                    reserved;
  unsigned char          multiHomeIndex;   //The particular index number for this IP address (multihoming)
}DevIpv4IfaceCfg;

SC1x Comments

flags

This bit field is defined as follows:


Bit 11:   Configure IP address via DHCP protocol

SC1x3/SC2x Comments

flags

This bit field is defined as follows:


Bit 7:   1: Configure IP address via DHCP protocol

Related Topics

Dev_Config_Iface() API

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.05	V1.00

typedef struct tag_DevIpv6IfaceCfg
{
  DevUserIfaceHandle               IfaceHandle;    // handle to identify the interface internal
  const struct sockaddr_storage *  IpAddrPtr;      //IP address
  int                              prefixlen;      // Prefix Length
  int                              reserved;
  int                              ipv6flags;
  void far *                       reservedPtr;     //reserved, currently not used
  unsigned char                    multiHomeIndex;  //The index for this IP address for multihoming
}DevIpv6IfaceCfg;

Comments

ipv6flags

This bit field is defined as follows:
Bit 11:   Enables auto interface ID

Related Topics

Dev_Config_Iface_IPv6() API

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	1.05	V1.00

typedef void  far *  DevUserLinkLayer ;

Comments

Handle type, to identiy link layer internally.   (Of no use to application.)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00