INtime SDK Help
hpeOpen
INtime SDK v7 > About INtime > Networking and I/O > High-Performance Ethernet > hpeOpen

Initializes an Ethernet interface by loading the appropriate device driver. The call provides PHY parameters and the desired interrupt mode. You can make this call only once for a given interface until you close the session by making a call to hpeClose.

HPESTATUS hpeOpen(
    const char *interface_name,
    DWORD phy_mac_params,
    DWORD interrupt_mode,
    HPEHANDLE *p_devhandle
);

Parameters

interface_name
A string that contains the interface name. The name identifies the device driver module to load and the instance of the interface. See Remarks section for more details.
phy_mac_params
A bitmap that defines the PHY parameters. A combination of one of each of the following groups of values defines the line speed and the duplex for the interface.
  • Line speed parameters
    SPEED_10 forces the interface to 10 Mbit line speed.
    SPEED_100 forces the interface to 100 Mbit line speed.
    SPEED_1000 forces the interface to 1 Gbit line speed.
    If a line speed parameter is not specified, the driver tries to detect the speed.
  • Duplex parameters
    DUPLEX_FULL forces the interface to full-duplex.
    DUPLEX_HALF forces the interface to half-duplex.
    If a duplex parameter is not specified, the driver tries to detect the duplex.
  • Link Status parameter

    WAIT_FOR_LINK (==0) is the default behavior. Unlike the legacy HPE, hpeOpen waits until the link is up or an error condition is detected.

    The NO_WAIT_FOR_LINK option makes hpeOpen behave like the legacy HPE. With NO_WAIT_FOR_LINK, hpeOpen the call returns immediately without waiting for the link up status. It is the caller's responsibility to check the link status by polling the link status using the hpeGetMediaStatus function.

  • Other parameters
    PROBE_ONLY instructs HPE driver not to open the device but only to probe the device. This parameter can be used to probe if the specified device exists or not. If the function returns E_OK, the device exists and it can be used for HPE operation. PROBE_ONLY must be used before opening any other HPE devices. If using PROBE_ONLY, interrupts may be verified by setting the interrupt parameter to ALL_INTERRUPTS. If the verification fails, the return value for hpeOpen may be the error return value from SetRtInterruptHandlerEx(). When PROBE_ONLY is specified, other phy_params parameters and p_devhandle are ignored. Since PROBE_ONLY doesn't open the device, calling hpeClose is not necessary. An example of using this parameter is provided in the HPE sample project.
    RETURN_RECEIVE_BUFFER enables "ReturnReceiveBuffer" mode. In this mode, the buffer returned by hpeGetReceiveBuffer is owned by user application and will not be overwritten by network device. User application needs to pass the ownership of the buffer back to network device by calling hpeReturnReceiveBuffer.
interrupt_mode
Determines the interrupt mode. May take one of the following values:
NO_INTERRUPT No interrupts will be generated (polled mode).
INPUT_INTERRUPT Interrupts will be generated for each received frame.
OUTPUT_INTERRUPT Interrupts will be generated for transmitted frame.
ALL_INTERRUPTS Interrupts will be generated for each received and each transmitted frame.
p_devhandle
A pointer to a location where the handle is to be returned. This value is only valid if the call succeeds.

Remarks

The interface name identifies which driver mode is to be loaded, and the instance of the device which is to be used. For example, the interface name ie1g0 indicates that the ie1g.rsl driver is to be loaded and that the first instance of a device which is controlled by that driver is to be used. This naming convention matches that used by the TCP/IP software stack.

When this call is made the driver module is loaded and the interface initialized according to the call parameters. A check is made that the interface is not already in use either by another HPE application or by the TCP/IP software stack.

Not all device driver modules used by the TCP/IP software stack also have HPE support. The device driver modules which may be used by HPE include ie1g, rtl1g, and rtl1gl.

Note: To get the name of required driver you might use istack.rta to list all devices passed to the INtime node and supported by the drivers. For example:
ldrta "%intime%network7\istack.rta" -a -L
For more details refer to the istack page.  

Return Values

A status value indicating the success or failure of the operation:

E_OK The operation completed successfully.
E_EXIST The name given in the interface_name parameter does not correspond to an existing interface.
E_NOT_CONFIGURED The driver specified by interface_name does not support the HPE API.
E_STATE The interface specified by interface_name is already open.
E_PARAM One of the fields phy_params or interrupt_mode is not valid.
E_INVALID_ADDR The p_devhandle parameter is not a valid pointer address.
E_IO An error occurred during hardware initialization, including failing to detect link up status.
E_TIME

The link status didn't change to up status within an internally defined timeout period.

Requirements

Versions Defined in Include Link to
INtime 4.0 intime/rt/include/hpeif2.h hpeif2.h hpeif2.lib
See Also

Network 7