17.2 Private Context Data Structure

The following example shows a fragment of a private context data structure used to manage the child-device-related information in a bus driver producing the Bus Specific Driver Override Protocol. The BusSpecificDriverOverride field is the protocol instance for the Bus Specific Driver Override Protocol. The NumberOfHandles field is the number of image handles that the GetDriver() function of the Bus Specific Driver Override Protocol returns for a single child device. The HandleBufferSize field is the number of handles allocated for the array HandleBuffer, and the HandleBuffer field is the array of driver image handles returned by the GetDriver() function of the Bus Specific Driver Override Protocol. The CR() macro provides a method to retrieve a pointer to an ABC_PRIVATE_DATA instance from a Bus Specific Driver Override Protocol This pointer. This macro is used by the GetDriver() function to retrieve the private context structure.

Example 163-Private Context Data Structure with a Bus Specific Driver Override Protocol

#define ABC_PRIVATE_DATA_SIGNATURE SIGNATURE_32('A','B','C',' ')

typedef struct {
  UINTN Signature;
  EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCOL BusSpecificDriverOverride;
  UINTN NumberOfHandles;
  UINTN HandleBufferSize;
  EFI_HANDLE *HandleBuffer;
} ABC_PRIVATE_DATA;

#define ABC_PRIVATE_DATA_FROM_BUS_SPECIFIC_DRIVER_OVERRIDE_THIS(a) \
  CR(a, ABC_PRIVATE_DATA, BusSpecificDriverOverride, ABC_PRIVATE_DATA_SIGNATURE)

This example shows how the private context data structure must be initialized by the bus driver when a child controller is discovered. This initialization is required for the examples of the AbcGetDriver() and AbcAddDriver() functions shown below to work correctly.

Example 164-Private Context Data Structure Initialization

Private->Signature = ABC_PRIVATE_DATA_SIGNATURE;
Private->BusSpecificDriverOverride.GetDriver = AbcGetDriver;
Private->NumberOfHandles = 0;
Private->HandleBufferSize = 0;
Private->HandleBuffer = NULL;