www.beck-ipc.com

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


    IPC@CHIP® Documentation Index

Data Structures

Here are the structures and other data types used by the TCP/IP Device Driver API.
All constants and data structures are defined in the TCPIPAPI.H header file.

Notes:
  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).
Related : Contents : Contents :

  • DevUserBuffer
  • DevUserBufferHandle
  • DevUserDriver
  • DevUserIfaceHandle
  • DevIpv4IfaceCfg
  • DevIpv6IfaceCfg
  • DevUserLinkLayer


  • DevUserBuffer


    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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    Top of list
    Index page

    DevUserBufferHandle


    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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    Top of list
    Index page

    DevUserDriver


                
    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
    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
    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
    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 flag is set to one of the following:

        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

    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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    Top of list
    Index page

    DevUserIfaceHandle


    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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    Top of list
    Index page

    DevIpv4IfaceCfg


                
    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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page

    DevIpv6IfaceCfg


                
    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/a1.05V1.00

    Top of list
    Index page

    DevUserLinkLayer


                
    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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    Top of list
    Index page


    End of document