2.2 The Hot Swap Engine

2.2 The Hot Swap Engine
	Chapter 2. Architectural Overview

The Hot Swap Engine acts as a generic Hot-Swap/Hot-Plug System Driver (as described in the Hot Swap Specification PICMG 2.1 R2.0). Its main task is to detect hot swap events and identify the hot swapped board's required resources. On Windows platforms you have the option to use the Hot Swap Engine to dynamically allocate the hot swapped board's resources (or de-allocate them upon the board removal).

2.2.1 Detecting Hot Swap Events

In order to detect live insertion/removal of CompactPCI devices from the bus, the Hot Swap Engine can use one of the following methods: polling the CompactPCI bus periodically, or polling the ENUM# signal^[2].

2.2.1.1 Polling the CompactPCI Bus

When the polling mechanism is activated by WD_WatchPciStart(), the Hot Swap Engine starts polling the bus periodically. This is Go-HotSwap's default mechanism for detection of hot swap events, because it allows compliance with all CompactPCI system configurations and board types (including basic and full hot swap boards).
The Hot Swap Specification PICMG 2.1 R1.0 allows the ENUM# signal to either drive an interrupt or be polled by the system software at regular intervals. The implementation and support of the ENUM# signal requires platform specific support, making the bus polling mechanism a better choice as the default mechanism for detection of hot swap events. Moreover, this architecture allows Go-HotSwap to enable hot swap with boards that do not implement the ENUM# signal at all.

After initiation, the Hot Swap Engine scans the CompactPCI bus to determine which devices are actually present. To do this, the Hot Swap Engine accesses the PCI Configuration Space and reads the Vendor ID register in each one of the possible 32 CompactPCI slots on each of the CompactPCI buses. The bus reports an attempt to read the Vendor ID of non-existent devices by returning a value of all 1's.
When a board is found, the Hot Swap Engine retrieves additional information, such as:

The board's device ID.
Whether the board is hot swap compatible or not (basic hot swap or full hot swap). If it is, the Hot Swap Engine continues to check:
1. Whether the status of the Handle Switch (activated by the lower ejector handle) is closed or open, by querying the Hot Swap Control and Status bits INS and EXT. Any alternations to the handle status detected in the next polling cycle will be used to determine whether the board was inserted (Handle Switch closed), or whether it is about to be removed (Handle Switch open).
2. Whether the board is a PCI bus master. A PCI bus master is a peripheral board containing a bridge that connects the parent bus on which it resides, to a child bus residing beyond the board, capable of carrying additional boards. The Hot Swap Engine checks this by accessing the Class Code register in the PCI configuration space of the board. If the board is a PCI bus master, the Hot Swap Engine locates the buses and devices residing beyond that bridge and adds them to the scan list. The same scan scheme is applied to a child bus as well.
3. Whether the board is a multifunction device, by querying the Header Type register in the PCI Configuration Space of the board. If it is, the Hot Swap Engine queries all the board's functions and adds them to the scan list.

At the end of this process the Hot Swap Engine constructs a list of existing buses, boards and functions.

At the next polling cycle the Hot Swap Engine will poll the listed buses, boards and functions, along with the PCI buses, updating the scan list according to changes that result from insertion/extraction of boards, into or out of the system.

From this point onward, the PCI buses are polled constantly at regular intervals, thus updating and constructing a new scan list whenever a change is made.

Once a new scan list has been constructed, the engine compares the new list to the old one. It sends a message concerning any modification it detected to the kernel-mode Messaging Mechanism, from where it can be extracted by the relevant processes (user-mode applications or device drivers).

The Hot Swap Engine will detect one of the following modifications:

The ejector handle of an existing board has been opened – the Hot Swap Engine sends a message asserting that the board is about to be removed and adds this data to its database. However, the engine does not allocate this board's resources to a newly inserted board until it has been physically removed from the chassis.
An existing board has been physically extracted from the chassis – The Hot Swap Engine sends a message to the kernel-mode Messaging Mechanism, asserting that the board has been removed, and adds this data to its database. The message is sent whether this board was extracted after all subscribed applications and drivers had terminated their access to the extracted board, or before (surprise extraction). The Hot Swap Engine also frees the board's resources to be reallocated when a new board is inserted into the chassis.
A new board has been inserted – If this board was found to be with hot swap abilities, but its ejector handle is still open, no resources are allocated to it. If the ejector handle of a hot swap aware board is closed, the engine allocates its required resources (see below) and sends the appropriate message to the kernel-mode Messaging Mechanism, including the vendor/device ID, bus, slot and function.

2.2.1.2 Monitoring the ENUM# signal

Go-HotSwap enables you to hook into the ENUM# signal in order to detect hot swap events. In this case you should not activate the polling mechanism, but instead instruct your application to listen to the ENUM# interrupt in order to detect the hot swap events. Listening to the ENUM# interrupt is done with WinDriver's interrupt handling API. Please refer to the WinDriver PCI Manual for detailed information.

2.2.2 Allocating Required Resources (Enumeration)


	The resource allocation is performed by the Hot Swap Engine unless you specify to use the operating system's Plug-and-Play Manager for this purpose. In `WD_WatchPciStart`() [A.1.3] the dwOptions field can be changed to specify that the operating system is responsible for resource allocation.

In non-hot swap systems, enumeration only takes place as the system boots.
The Go-HotSwap software enables live enumeration under a running system. When a hot swap board is inserted into the system, the Hot Swap Engine performs the process of Dynamic Configuration, whereby it allocates system resources to the board^[3] while the system is running.

When using the polling method, the Hot Swap Engine automatically allocates (or de-allocates) the required resources. When using the ENUM# signal to detect hot swap events, the Go-HotSwap function WD_HsEventSend() should be called in order to allocate (or de-allocate) the required resources. Please refer to the Go-HotSwap Function Reference for more information regarding this function.

The allocated system resources are some or all of the following:

2.2.2.1 I/O, Memory and Prefetchable Memory

The resource allocation process differs in the case of a simple board and a PCI Bus Master.

Allocating I/O, Memory and Prefetchable Memory for a simple board:
When a simple board is inserted into one of the slots, the Hot Swap Engine first queries its required resources by accessing the PCI configuration space registers. The Hot Swap Engine queries all 6 BARs (Base Address Registers) of the board, and identifies the required resources of each BAR. These resources could be I/O, memory and prefetchable memory. It then allocates the board's required resources accordingly.
Allocating I/O, Memory and Prefetchable Memory for a PCI bus master:
When a PCI bus master is inserted into one of the slots, resources should be allocated for the PCI bus master itself, as well as for the child bus and for any board residing on the child bus beyond the bridge. Again, these resources could be I/O, Memory and Prefetchable Memory. The Hot Swap Engine first queries the 2 BARs of the PCI bus master and identifies the resources required by each BAR; it then allocates the board's required resources accordingly. The Hot Swap Engine also allocates resources to the child bus, according to a predefined algorithm. The Hot Swap Engine then scans the child bus to determine what resources are to be allocated for any board located on the child bus. At this stage, the engine also sets a range of bus/slot numbers available at the child bus.

2.2.2.2 Interrupts

When the Hot Swap Engine detects a board that requires interrupts, it assigns the interrupts as follows:

On x86 machines, if the board is inserted into a slot that is listed on the interrupt routing table located in the BIOS, the engine finds the appropriate register in the APIC (Advanced Programmable Interrupt Controller) and writes the interrupt number to the board.
On PPC machines, or if the board is inserted into a slot that is not listed in the interrupt routing table, the engine recursively calculates the interrupt line and then finds the appropriate register in the APIC and writes the interrupt number to the board.

2.2.2.3 Command Register

In order to access the board, the engine sets the Command register in the PCI configuration space to a predefined value, as defined in the PCI specification R2.2.

When the allocation process is complete, the relevant drivers/applications are notified by the Hot Swap Engine of the boards'/ devices' newly allocated resources. This message is either transferred directly to the driver (if a hot swap aware driver had been developed), or via the Go-HotSwap Configuration Manager (if a legacy PCI driver had been used without any driver code programming or modifications).

^[2]A signal provided by CompactPCI full hot swap boards and by hot swap friendly/ready CompactPCI silicon, in order to notify the system host that a board was either freshly inserted or is about to be extracted.

^[3]see PICMG Hot Swap Specification 2.1 R2.0.


Chapter 2. Architectural Overview		2.3 Kernel-Mode Messaging Mechanism