4.3 Using the API

4.3 Using the API
	Chapter 4. Using Go-HotSwap

Go-HotSwap and the included WinDriver toolkit provide an API with which you can achieve hot swap capabilities. From a process point of view, if you choose this method, there are two development challenges:

Generate the driver's hardware access code.
Add hot swap capabilities to the driver.

Here is a more detailed description of these steps:

4.3.1 Generate Driver's Hardware Access Code

If you have not yet developed hardware access code, we recommend you use Jungo's WinDriver toolkit, for it dramatically reduces development time; moreover, the generated code has cross operating system capabilities. Detailed information on driver development issues (such as interrupt handling, DMA, improving performance, etc.), and the WinDriver tools, can be found in the WinDriver PCI Manual.

The WinDriver toolkit includes a wizard that helps generate your skeletal driver's hardware access code. During this process, you are asked to select your driver's options, one of which is Plug-and-Play notifications, another is power management notifications. Make sure to select these options in order to use WinDriver's application with the Hot Swap Engine, as demonstrated in Figure 4.1.

Figure 4.1 Notification Events

As explained earlier, it is not a requirement to have the driver's hardware access code generated with WinDriver; hot swap capabilities can also be achieved with drivers developed in other ways.

4.3.2 Add Hot Swap Capabilities to the Driver

In order to make your driver or application hot swap aware and to utilize the hot swap services provided by Go-HotSwap, you must add the Go-HotSwap API, as well as some relevant WinDriver API. A list of the API can be found in the Go-HotSwap Function Reference chapter, later on in this manual.

The API should be used according the following procedure:

Activate the Hot Swap Engine.
The Hot Swap Engine should be activated in order for the application to receive Hot Swap services, which is done by calling the function WD_WatchPciStart() [A.1.3]. Each application should call WD_WatchPciStart() before implementing another Go-HotSwap API. You can call it even if the Hot Swap Engine has already been activated; so there is no need to check if the Hot Swap Engine is activated or not.
After the Engine is activated, it starts detecting hot swap events, and accordingly, dynamically allocates/de-allocates resources.
Register your application to receive notifications.
In order for your application to utilize the hot swap services provided by the Hot Swap Engine and to become hot swap aware, you should register your application to receive notifications about hot swap events, according to a user defined set of criteria. Do this by calling the function EventRegister() [A.2.6]. This function allows you to determine the devices and types of events for which you wish to receive notifications.
EventRegister() [A.2.6] receives as one of its parameters (func) an event handler callback function, which will be called for each occurrence of a registered event. The parameters of the event handler callback include information regarding the event that occurred, as well as data that was received from the user in the call to EventRegister() (see the pData parameter).
You should implement your event handler callback to perform any functionality pertinent to the event that occurred. For example, if you receive a notification regarding the insertion of a VoIP board into the chassis, your event handler callback can start the board's specific functionality. A simpler example would be to just print a message from your event handler to the screen, describing the hot swap event that has just occurred, as demonstrated by the hs_detect utility.
When you no longer need to handle hot swap events, call the function EventUnregister() [A.2.7] to unregister your application from receiving events notifications.

The API can be also used to light the blue led of a cPCI board when it is safe (from the application's perspective) to physically remove it from the backplane. The proper procedure is:

Instruct the Hot Swap Engine to wait for an acknowledgement from the application before lighting the blue led.
Once the application is notified that the relevant board is about to be removed, it should follow the relevant procedure to ensure safe removal of the board, for example, stop communicating with the board.
Only at this stage may the application acknowledge the event to the Hot Swap Engine.
The Hot Swap Engine lights the blue led. The operator will then notice the blue led is lit, indicating that it is safe to physically remove the board.

The last stage of the hot swap procedure is to turn off the Hot Swap Engine. This is done by calling the WD_WatchPciStop() [A.1.4] function.


4.2 What Does the Go-HotSwap Package Include?		4.4 The Configuration Manager