8.3 Allocating private context data structures
Private context data structures are allocated in the
Start() function of the Driver Binding Protocol. The service that is typically used to allocate the private context data structures is the UEFI Boot Service AllocatePool(). The following example shows the generic template for allocating and zeroing a private context data structure in the Start() function of the Driver Binding Protocol. In this example, the UEFI Boot Service SetMem() is used to fill the allocated buffer with zeros. This code example shows only a fragment from the Start() function. Chapter 9 of this guide covers the services that are produced by the Driver Binding Protocol in more detail. The code examples that follow show how the implementation of Start() can be simplified by using the EDK II library MemoryAllocationLib.#include <Uefi.h>
#include <Protocol/DriverBinding.h>
#include <Protocol/DevicePath.h>
#include <Library/UefiBootServicesTableLib.h>
EFI_STATUS
EFIAPI
<<DriverName>>DriverBindingStart (
IN EFI_DRIVER_BINDING_PROTOCOL *This,
IN EFI_HANDLE ControllerHandle,
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
)
{
EFI_STATUS Status;
<<DRIVER_NAME>>_PRIVATE_DATA Private;
//
// Allocate the private context data structure
//
Status = gBS->AllocatePool (
EfiBootServicesData,
sizeof ( <<DRIVER_NAME>>_PRIVATE_DATA),
(VOID **)&Private
);
if (EFI_ERROR (Status)) {
return Status;
}
//
// Clear the contents of the allocated buffer
//
gBS->SetMem (Private,sizeof(<<DRIVER_NAME>>_PRIVATE_DATA),0);
}
The example below shows the same generic template for the
Start() function above except that it uses the EDK II library MemoryAllocationLib to allocate and zero the private context data structure.#include <Uefi.h>
#include <Protocol/DriverBinding.h>
#include <Protocol/DevicePath.h>
#include <Library/MemoryAllocationLib.h>
EFI_STATUS
EFIAPI
<<DriverName>>DriverBindingStart (
IN EFI_DRIVER_BINDING_PROTOCOL *This,
IN EFI_HANDLE ControllerHandle,
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
)
{
<<DRIVER_NAME>>_PRIVATE_DATA Private;
//
// Allocate and zero the private context data structure
//
Private = AllocateZeroPool (sizeof ( <<DRIVER_NAME>>_PRIVATE_DATA));
if (Private == NULL) {
return EFI_OUT_OF_RESOURCES;
}
}
The following example shows a code fragment from the
DiskIoDxe driver in the MdeModulePkg that allocates and initializes the private context data structure from a template structure. A template structure is an instance of the private context structure with most of the fields pre-initialized. This style produces UEFI Drivers that execute faster and produce smaller executables than UEFI Drivers that initialize each field of the private context data structure in the Start() function.#include <Uefi.h>
#include <Protocol/DriverBinding.h>
#include <Protocol/DevicePath.h>
#include <Protocol/DiskIo.h>
#include <Library/MemoryAllocationLib.h>
//
// Template for DiskIo private data structure.
// The pointer to BlockIo protocol interface is assigned dynamically.
//
DISK_IO_PRIVATE_DATA gDiskIoPrivateDataTemplate = {
DISK_IO_PRIVATE_DATA_SIGNATURE,
{
EFI_DISK_IO_PROTOCOL_REVISION,
DiskIoReadDisk,
DiskIoWriteDisk
},
NULL
};
EFI_STATUS
EFIAPI
DiskIoDriverBindingStart (
IN EFI_DRIVER_BINDING_PROTOCOL *This,
IN EFI_HANDLE ControllerHandle,
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
)
{
EFI_STATUS Status;
DISK_IO_PRIVATE_DATA *Private;
//
// Initialize the Disk IO device instance.
//
Private = AllocateCopyPool (
sizeof (DISK_IO_PRIVATE_DATA),
&gDiskIoPrivateDataTemplate
);
if (Private == NULL) {
Status = EFI_OUT_OF_RESOURCES;
goto ErrorExit;
}
}
Last modified 2yr ago