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