Appendix A. Function Reference

A.1 Go-HotSwap

A.1.1 General

Add the Go-HotSwap functions described in this chapter to your code in order to make your application/driver hot swap aware and to utilize the Go-HotSwap services: register your driver or application to receive notifications and information about hot swap events (insertion/removal of your cPCI board), acknowledge receipt of the hot swap notification (to light the Blue LED) and perform re-enumeration according to user permissions.

This section describes the calling sequence used in hs_activate, but you may write a new application based on the given samples. You can refer to the hs_detect, hs_activate and hs_reenum utilities, (GoHotSwap\hotswap\... - source code included) as samples for implementation of the Go-HotSwap API. You may also refer to the files windrvr.h, windrvr_events.h and windrvr_int_thread.h for API definitions.


	This section describes the Go-HotSwap calling sequence and the Go-HotSwap API functions. In addition to the Go-HotSwap API functions, the Go-HotSwap calling sequence includes WinDriver API functions, which are described in detail in the WinDriver Function Reference.

A.1.2 Calling Sequence

Figure A.1 Go-HotSwap Calling Sequence

All Go-HotSwap (and WinDriver) functions should receive a HANDLE parameter as the first argument, which is a value returned from the WinDriver function WD_Open(). Therefore this function must be called before any other Go-HotSwap or WinDriver function is called. For more information about the WD_Open() function, refer to section A.2.1 of the manual.
We recommend you call the WinDriver WD_Version() function A.2.2 after calling WD_Open() and before calling any other Go-HotSwap/WinDriver function. Its purpose is to return the Go-HotSwap/WinDriver kernel module (windrvr6) version number, thus providing the means to verify that your application is version compatible with the Go-HotSwap/WinDriver kernel module.
We recommend you use Go-HotSwap function wrappers in order to conveniently handle hot swap events.
The EventRegister() function [A.2.6] wraps the calls to the low-level WD_EventRegister(), WD_EventPull() and WD_EventSend() WinDriver functions.
The EventUnregister() function [A.2.7] wraps the calls to the low-level WinDriver WD_EventUnregister() function.
You must call WD_WatchPciStart() to activate the Hot Swap Engine, and WD_WatchPciStop() to stop the Hot Swap Engine.
The functions that compose the wrapper functions can be called separately instead of using the wrappers, according to the following sequence:
Figure A.2 Low-Level Events Calling Sequence
For more details regarding the Go-HotSwap functions, please refer to the function reference below. For more details regarding the WinDriver functions, please refer to the WinDriver PCI Manual(included in Go-HotSwap package).

A.1.3 WD_WatchPciStart()

Purpose

• Starts the Go-HotSwap Hot Swap Engine polling cycle, with the option to exclude devices from the polling cycle.

Prototype

void WD_WatchPciStart(
  HANDLE hWD,
  WD_HS_WATCH *pHsWatch);

Parameters

Name	Type	Input/Output
hWD	HANDLE	Input
pHsWatch	WD_HS_WATCH*
• handle	DWORD	Output
• dwOptions	DWORD	Input
• dwNumMatchTables	DWORD	Input
• matchTables	WD_HS_MATCH_TABLE[1]
* wVendorId	WORD	Input
* wDeviceId	WORD	Input
* wSubVendorId	WORD	Input
* wSubDeviceId	WORD	Input
* dwOptions	DWORD	Input

Description

Name	Description
hWD	Handle received from `WD_Open`() [A.2.1]
pHsWatch	Pointer to a hot swap watch information structure:
handle	Handle to be used in calls to `WD_WatchPciStop`() [A.1.4], or `INVALID_HANDLE_VALUE` if the operation failed
dwOptions	Can be either: • Zero: Use the Go-HotSwap Hot Swap Engine for the hot-swapped board's resource allocation. • `WD_CPCI_PNP_SUPPORT` – Use the operating system's Plug-and-Play support.
dwNumMatchTables	Number of match tables in the `matchTables` array
matchTables	Array of hot swap match tables:
wVendorId	PCI vendor ID to exclude from polling cycle
wDeviceId	PCI device ID to exclude from polling cycle
wSubVendorId	PCI sub-vendor ID to exclude from polling cycle
wSubDeviceId	PCI sub-device ID to exclude from polling cycle
dwOptions	A bit-mask, which can be set to either: • Zero: The Go-HotSwap Hot Swap Engine polls all devices. • `WD_MATCH_EXCLUDE` – The Go-HotSwap Hot Swap Engine polls all devices excluding the devices specified in the match table. You have the option of excluding specific devices or all devices of a specified vendor or sub-vendor, or any specified combination.

Remarks

When the polling cycle is initiated by WD_WatchPciStart(), the Hot Swap Engine starts detecting hot swap events and dynamically allocates (or de-allocates) the required resources accordingly. After calling WD_WatchPciStart(), you may call EventRegister() [A.2.6] to receive hot swap events notifications.

Example

See WD_WatchPciStop() [A.1.4] example.

A.1.4 WD_WatchPciStop()

Purpose

• Stops the Go-HotSwap Hot Swap Engine polling cycle.

Prototype

void WD_WatchPciStop(
    HANDLE hWD,
    WD_HS_WATCH *pHsWatch);

Parameters

Name	Type	Input/Output
hWD	HANDLE	Input
pHsWatch	WD_HS_WATCH*
• handle	DWORD	Input
• dwOptions	DWORD	Input
• dwNumMatchTables	DWORD	Input
• matchTables	WD_HS_MATCH_TABLE[1]
* wVendorId	WORD	Input
* wDeviceId	WORD	Input
* wSubVendorId	WORD	Input
* wSubDeviceId	WORD	Input
* dwOptions	DWORD	Input

Description

Name	Description
hWD	Handle received from `WD_Open`() [A.2.1]
pHsWatch	Pointer to a hot swap watch information structure:
handle	Handle returned from `WD_WatchPciStart`() [A.1.3]
dwOptions	Reserved for future use
dwNumMatchTables	Number of match tables in the `matchTables` array
matchTables	Array of hot swap match tables – see description of `WD_WatchPciStart`() [A.1.3] for details

Example

The following example demonstrates the use of WD_WatchPciStart() and WD_WatchPciStop():

WD_HS_WATCH hWatch;
BZERO(hWatch);

WD_WatchPciStart(hWD, &hWatch);
if (!hWatch.handle)
{
    printf("Failed Watching CompactPCI bus\n");
    return -1;
}
/* Use the rest of the Hot Swap API in this part of the code
   When completed, stop the Hot Swap Engine */
if (hWatch.handle)
    WD_WatchPciStop(hWD, &hWatch);


4.4 The Configuration Manager		A.2 WinDriver Functions Used by Go-HotSwap