4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Provides services to notify the PCI bus driver that some events have happened
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync in a hot-plug controller (such as a PC Card socket, or PHPC), and to ask the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync PCI bus driver to create or destroy handles for PCI-like devices.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync A hot-plug capable PCI bus driver should produce the EFI PCI Hot Plug Request
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync protocol. When a PCI device or a PCI-like device (for example, 32-bit PC Card)
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is installed after PCI bus does the enumeration, the PCI bus driver can be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync notified through this protocol. For example, when a 32-bit PC Card is inserted
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync into the PC Card socket, the PC Card bus driver can call interface of this
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync protocol to notify PCI bus driver to allocate resource and create handles for
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync this PC Card.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL is installed by the PCI bus driver on a
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync separate handle when PCI bus driver starts up. There is only one instance in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the system. Any driver that wants to use this protocol must locate it globally.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The EFI_PCI_HOTPLUG_REQUEST_PROTOCOL allows the driver of hot-plug controller,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync for example, PC Card Bus driver, to notify PCI bus driver that an event has
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync happened in the hot-plug controller, and the PCI bus driver is requested to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync create (add) or destroy (remove) handles for the specified PCI-like devices.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync For example, when a 32-bit PC Card is inserted, this protocol interface will
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync be called with an add operation, and the PCI bus driver will enumerate and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync start the devices inserted; when a 32-bit PC Card is removed, this protocol
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync interface will be called with a remove operation, and the PCI bus driver will
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync stop the devices and destroy their handles. The existence of this protocol
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync represents the capability of the PCI bus driver. If this protocol exists in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync system, it means PCI bus driver is hot-plug capable, thus together with the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync effort of PC Card bus driver, hot-plug of PC Card can be supported. Otherwise,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the hot-plug capability is not provided.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Copyright (c) 2006 - 2009, Intel Corporation. All rights reserved.<BR>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This program and the accompanying materials
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync are licensed and made available under the terms and conditions of the BSD License
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync which accompanies this distribution. The full text of the license may be found at
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @par Revision Reference:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This Protocol is defined in UEFI Platform Initialization Specification 1.2
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Volume 5: Standards
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Global ID for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 0x19cb87ab, 0x2cb9, 0x4665, {0x83, 0x60, 0xdd, 0xcf, 0x60, 0x54, 0xf7, 0x9d} \
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Forward declaration for EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL EFI_PCI_HOTPLUG_REQUEST_PROTOCOL;
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Enumeration of PCI hot plug operations
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef enum {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// The PCI bus driver is requested to create handles for the specified devices.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// An array of EFI_HANDLE is returned, with a NULL element marking the end of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// the array.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// The PCI bus driver is requested to destroy handles for the specified devices.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This function is used to notify PCI bus driver that some events happened in a
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync hot-plug controller, and the PCI bus driver is requested to start or stop
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync specified PCI-like devices.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This function allows the PCI bus driver to be notified to act as requested when
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync a hot-plug event has happened on the hot-plug controller. Currently, the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync operations include add operation and remove operation. If it is a add operation,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the PCI bus driver will enumerate, allocate resources for devices behind the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync hot-plug controller, and create handle for the device specified by RemainingDevicePath.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The RemainingDevicePath is an optional parameter. If it is not NULL, only the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync specified device is started; if it is NULL, all devices behind the hot-plug
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync controller are started. The newly created handles of PC Card functions are
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync returned in the ChildHandleBuffer, together with the number of child handle in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync NumberOfChildren. If it is a remove operation, when NumberOfChildren contains
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync a non-zero value, child handles specified in ChildHandleBuffer are stopped and
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync destroyed; otherwise, PCI bus driver is notified to stop managing the controller
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] This A pointer to the EFI_PCI_HOTPLUG_REQUEST_PROTOCOL
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Operation The operation the PCI bus driver is requested
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Controller The handle of the hot-plug controller.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] RemainingDevicePath The remaining device path for the PCI-like
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync hot-plug device. It only contains device
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync path nodes behind the hot-plug controller.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync It is an optional parameter and only valid
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync when the Operation is a add operation. If
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync it is NULL, all devices behind the PC Card
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync socket are started.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in,out] NumberOfChildren The number of child handles. For an add
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync operation, it is an output parameter. For
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync a remove operation, it's an input parameter.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync When it contains a non-zero value, children
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync handles specified in ChildHandleBuffer are
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync destroyed. Otherwise, PCI bus driver is
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync notified to stop managing the controller
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in,out] ChildHandleBuffer The buffer which contains the child handles.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync For an add operation, it is an output
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync parameter and contains all newly created
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync child handles. For a remove operation, it
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync contains child handles to be destroyed when
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync NumberOfChildren contains a non-zero value.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync It can be NULL when NumberOfChildren is 0.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync It's the caller's responsibility to allocate
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync and free memory for this buffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS The handles for the specified device have been
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync created or destroyed as requested, and for an
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync add operation, the new handles are returned in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ChildHandleBuffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER Operation is not a legal value.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER Controller is NULL or not a valid handle.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER NumberOfChildren is NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync remove and NumberOfChildren contains a non-zero
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER ChildHandleBuffer is NULL while Operation is add.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_OUT_OF_RESOURCES There are no enough resources to start the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Provides services to notify PCI bus driver that some events have happened in
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// a hot-plug controller (for example, PC Card socket, or PHPC), and ask PCI bus
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// driver to create or destroy handles for the PCI-like devices.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// Notify the PCI bus driver that some events have happened in a hot-plug
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// controller (for example, PC Card socket, or PHPC), and ask PCI bus driver
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// to create or destroy handles for the PCI-like devices. See Section 0 for
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// a detailed description.