@CHIP-RTOS C Library - TCP/IP API

Dev_Open_Interface

Install user device driver.

int Dev_Open_Interface(DevUserDriver far * DriverInfo,
                     int * errorcode);

Parameters

DriverInfo

Pointer to user driver information.

errorcode

Output parameter:  Failure code, 0 on success.

Return Value

0: success
-1: See reported errorcode .

Comments

The caller must fill in the referenced DevUserDriver object prior to calling.   On the initial call of this API for a particular device, the IfaceHandle member must be NULL.   On success, this API will put the new device's handle into this member for use with the various driver related API.

An installed device can be reconfigured by first calling the Dev_Close_Interface() and then calling this Dev_Open_Interface() again, this time with the IfaceHandle member of the DevUserDriver still set to the value output from the first call.

An Ethernet interface can be configured using DHCP by setting the use_dhcp member to 1.   In this case, the Dev_Wait_DHCP_Complete() should be called following a successful call to this API in order to retrieve the IPv4 address and network mask.

This API performs two steps during its execution.   The first step is to add the new device to the TCP/IP stack (this step is irreversible).   This step is performed only when the IfaceHandle member was set to NULL by the caller.   This step will fail with error code 237 if a device with the same name has already been installed and that device is not currently closed.   The Dev_Close_Interface() API is used to close a device.

The second step is to configure the device.   This second step is performed only if the device has been added successfully (either on this immediate call, or a previous one) and the DEV_ADD_ONLY flag is not set in the iface_type member of the referenced DevUserDriver object.

Go here for further explanations and an example with source code.

Once a device has been installed, there is no mechanism short of a system reset to remove that device from the TCP/IP stack.   However, you can deactivate the device with the Dev_Close_Interface() API. This step is important prior to a driver program exit in order that another instance of the driver program can later use this API to open this same device again.   On this second installation, the new program instance's callback vectors will be installed.

See Also

Dev_Close_Interface        Dev_Recv_Interface        Dev_Recv_Wait
Dev_Notify_ISR        Dev_Get_Buffer        Dev_Send_Complete
Dev_Wait_DHCP_Complete        Dev_PPP_Register_Chap        Dev_PPP_Register_Pap
Dev_PPP_Set_Option        Dev_PPP_Get_Peer_IP        Dev_PPP_Get_Peer_DNSIP
Dev_PPP_Get_Peer_IPv6                

RTOS API

This library function invokes a RTOS software interrupt. Refer to this RTOS API function's documentation for more details.

On SC1x3/SC2x (RTOS version >=1.13, CLIB version >=2.10) there's also a version of this function which uses dynamic linking instead of a software interrupt, which reduces the function's overhead and thus speeds up your application. This function's name is Dev_Open_Interface_Dyn. You should however not use this function directly. Instead you should add the define TCPIP_DYN_LINK_DEV to your program before including the CLIB's header file(s):

#define TCPIP_DYN_LINK_DEV
#include <clib.h>

This will map the original function's name to the dynamic linking version. This way you can also easily switch existing programs to dynamic linking.

Related Topics

Example - Installing device driver

Supported since or modified in @CHIP-RTOS version

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