MdeModulePkg/Bus/I2c/I2cDxe/I2cDxe.h

   1 /** @file
   2   Private data structures for the I2C DXE driver.
   3
   4   This file defines common data structures, macro definitions and some module
   5   internal function header files.
   6
   7   Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __I2C_DXE_H__
  13 #define __I2C_DXE_H__
  14
  15 #include <Uefi.h>
  16 #include <Library/BaseMemoryLib.h>
  17 #include <Library/DebugLib.h>
  18 #include <Library/DevicePathLib.h>
  19 #include <Library/MemoryAllocationLib.h>
  20 #include <Library/TimerLib.h>
  21 #include <Library/UefiBootServicesTableLib.h>
  22 #include <Library/UefiDriverEntryPoint.h>
  23 #include <Library/UefiLib.h>
  24
  25 #include <Protocol/DriverBinding.h>
  26 #include <Protocol/I2cEnumerate.h>
  27 #include <Protocol/I2cHost.h>
  28 #include <Protocol/I2cIo.h>
  29 #include <Protocol/I2cMaster.h>
  30 #include <Protocol/I2cBusConfigurationManagement.h>
  31 #include <Protocol/LoadedImage.h>
  32
  33 #define I2C_DEVICE_SIGNATURE          SIGNATURE_32 ('I', '2', 'C', 'D')
  34 #define I2C_HOST_SIGNATURE            SIGNATURE_32 ('I', '2', 'C', 'H')
  35 #define I2C_REQUEST_SIGNATURE         SIGNATURE_32 ('I', '2', 'C', 'R')
  36
  37 //
  38 // Synchronize access to the list of requests
  39 //
  40 #define TPL_I2C_SYNC                  TPL_NOTIFY
  41
  42 //
  43 //  I2C bus context
  44 //
  45 typedef struct {
  46   EFI_I2C_ENUMERATE_PROTOCOL       *I2cEnumerate;
  47   EFI_I2C_HOST_PROTOCOL            *I2cHost;
  48   EFI_HANDLE                       Controller;
  49   EFI_DEVICE_PATH_PROTOCOL         *ParentDevicePath;
  50   EFI_HANDLE                       DriverBindingHandle;
  51 } I2C_BUS_CONTEXT;
  52
  53 //
  54 // I2C device context
  55 //
  56 typedef struct {
  57   //
  58   // Structure identification
  59   //
  60   UINT32                        Signature;
  61
  62   //
  63   // I2c device handle
  64   //
  65   EFI_HANDLE                    Handle;
  66
  67   //
  68   // Upper level API to support the I2C device I/O
  69   //
  70   EFI_I2C_IO_PROTOCOL           I2cIo;
  71
  72   //
  73   // Device path for this device
  74   //
  75   EFI_DEVICE_PATH_PROTOCOL      *DevicePath;
  76
  77   //
  78   // Platform specific data for this device
  79   //
  80   CONST EFI_I2C_DEVICE          *I2cDevice;
  81
  82   //
  83   // Context for the common I/O support including the
  84   // lower level API to the host controller.
  85   //
  86   I2C_BUS_CONTEXT               *I2cBusContext;
  87 } I2C_DEVICE_CONTEXT;
  88
  89 #define I2C_DEVICE_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_DEVICE_CONTEXT, I2cIo, I2C_DEVICE_SIGNATURE)
  90
  91 //
  92 // I2C Request
  93 //
  94 typedef struct {
  95   //
  96   // Signature
  97   //
  98   UINT32                            Signature;
  99
 100   //
 101   // Next request in the pending request list
 102   //
 103   LIST_ENTRY                        Link;
 104
 105   //
 106   // I2C bus configuration for the operation
 107   //
 108   UINTN                             I2cBusConfiguration;
 109
 110   //
 111   // I2C slave address for the operation
 112   //
 113   UINTN                             SlaveAddress;
 114
 115   //
 116   // Event to set for asynchronous operations, NULL for
 117   // synchronous operations
 118   //
 119   EFI_EVENT                         Event;
 120
 121   //
 122   // I2C operation description
 123   //
 124   EFI_I2C_REQUEST_PACKET            *RequestPacket;
 125
 126   //
 127   // Optional buffer to receive the I2C operation completion status
 128   //
 129   EFI_STATUS                        *Status;
 130 } I2C_REQUEST;
 131
 132 #define I2C_REQUEST_FROM_ENTRY(a)         CR (a, I2C_REQUEST, Link, I2C_REQUEST_SIGNATURE);
 133
 134 //
 135 // I2C host context
 136 //
 137 typedef struct {
 138   //
 139   // Structure identification
 140   //
 141   UINTN Signature;
 142
 143   //
 144   // Current I2C bus configuration
 145   //
 146   UINTN I2cBusConfiguration;
 147
 148   //
 149   // I2C bus configuration management event
 150   //
 151   EFI_EVENT I2cBusConfigurationEvent;
 152
 153   //
 154   // I2C operation completion event
 155   //
 156   EFI_EVENT I2cEvent;
 157
 158   //
 159   // I2C operation and I2C bus configuration management status
 160   //
 161   EFI_STATUS Status;
 162
 163   //
 164   // I2C bus configuration management operation pending
 165   //
 166   BOOLEAN I2cBusConfigurationManagementPending;
 167
 168   //
 169   // I2C request list maintained by I2C Host
 170   //
 171   LIST_ENTRY                  RequestList;
 172
 173   //
 174   // Upper level API
 175   //
 176   EFI_I2C_HOST_PROTOCOL       I2cHost;
 177
 178   //
 179   // I2C bus configuration management protocol
 180   //
 181   EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *I2cBusConfigurationManagement;
 182
 183   //
 184   // Lower level API for I2C master (controller)
 185   //
 186   EFI_I2C_MASTER_PROTOCOL *I2cMaster;
 187 } I2C_HOST_CONTEXT;
 188
 189 #define I2C_HOST_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_HOST_CONTEXT, I2cHost, I2C_HOST_SIGNATURE)
 190
 191 //
 192 // Global Variables
 193 //
 194 extern EFI_COMPONENT_NAME_PROTOCOL    gI2cBusComponentName;
 195 extern EFI_COMPONENT_NAME2_PROTOCOL   gI2cBusComponentName2;
 196 extern EFI_DRIVER_BINDING_PROTOCOL    gI2cBusDriverBinding;
 197
 198 extern EFI_COMPONENT_NAME_PROTOCOL    gI2cHostComponentName;
 199 extern EFI_COMPONENT_NAME2_PROTOCOL   gI2cHostComponentName2;
 200 extern EFI_DRIVER_BINDING_PROTOCOL    gI2cHostDriverBinding;
 201
 202 /**
 203   Start the I2C driver
 204
 205   This routine allocates the necessary resources for the driver.
 206
 207   This routine is called by I2cBusDriverStart to complete the driver
 208   initialization.
 209
 210   @param[in] I2cBus                   Address of an I2C_BUS_CONTEXT structure
 211   @param[in] Controller               Handle to the controller
 212   @param[in] RemainingDevicePath      A pointer to the remaining portion of a device path.
 213
 214   @retval EFI_SUCCESS                 Driver API properly initialized
 215
 216 **/
 217 EFI_STATUS
 218 RegisterI2cDevice (
 219   IN I2C_BUS_CONTEXT           *I2cBus,
 220   IN EFI_HANDLE                 Controller,
 221   IN EFI_DEVICE_PATH_PROTOCOL  *RemainingDevicePath
 222   );
 223
 224 /**
 225   Unregister an I2C device.
 226
 227   This function removes the protocols installed on the controller handle and
 228   frees the resources allocated for the I2C device.
 229
 230   @param  This                  The pointer to EFI_DRIVER_BINDING_PROTOCOL instance.
 231   @param  Controller            The controller handle of the I2C device.
 232   @param  Handle                The child handle.
 233
 234   @retval EFI_SUCCESS           The I2C device is successfully unregistered.
 235   @return Others                Some error occurs when unregistering the I2C device.
 236
 237 **/
 238 EFI_STATUS
 239 UnRegisterI2cDevice (
 240   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,
 241   IN  EFI_HANDLE                     Controller,
 242   IN  EFI_HANDLE                     Handle
 243   );
 244
 245 /**
 246   Create a path for the I2C device
 247
 248   Append the I2C slave path to the I2C master controller path.
 249
 250   @param[in] I2cDeviceContext           Address of an I2C_DEVICE_CONTEXT structure.
 251   @param[in] BuildControllerNode        Flag to build controller node in device path.
 252
 253   @retval EFI_SUCCESS           The I2C device path is built successfully.
 254   @return Others                It is failed to built device path.
 255
 256 **/
 257 EFI_STATUS
 258 I2cBusDevicePathAppend (
 259   IN I2C_DEVICE_CONTEXT     *I2cDeviceContext,
 260   IN BOOLEAN                BuildControllerNode
 261   );
 262
 263 /**
 264   Queue an I2C transaction for execution on the I2C device.
 265
 266   This routine must be called at or below TPL_NOTIFY.  For synchronous
 267   requests this routine must be called at or below TPL_CALLBACK.
 268
 269   This routine queues an I2C transaction to the I2C controller for
 270   execution on the I2C bus.
 271
 272   When Event is NULL, QueueRequest() operates synchronously and returns
 273   the I2C completion status as its return value.
 274
 275   When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
 276   indicating that the asynchronous I2C transaction was queued.  The values
 277   above are returned in the buffer pointed to by I2cStatus upon the
 278   completion of the I2C transaction when I2cStatus is not NULL.
 279
 280   The upper layer driver writer provides the following to the platform
 281   vendor:
 282
 283   1.  Vendor specific GUID for the I2C part
 284   2.  Guidance on proper construction of the slave address array when the
 285       I2C device uses more than one slave address.  The I2C bus protocol
 286       uses the SlaveAddressIndex to perform relative to physical address
 287       translation to access the blocks of hardware within the I2C device.
 288
 289   @param[in] This               Pointer to an EFI_I2C_IO_PROTOCOL structure.
 290   @param[in] SlaveAddressIndex  Index value into an array of slave addresses
 291                                 for the I2C device.  The values in the array
 292                                 are specified by the board designer, with the
 293                                 third party I2C device driver writer providing
 294                                 the slave address order.
 295
 296                                 For devices that have a single slave address,
 297                                 this value must be zero.  If the I2C device
 298                                 uses more than one slave address then the
 299                                 third party (upper level) I2C driver writer
 300                                 needs to specify the order of entries in the
 301                                 slave address array.
 302
 303                                 \ref ThirdPartyI2cDrivers "Third Party I2C
 304                                 Drivers" section in I2cMaster.h.
 305   @param[in] Event              Event to signal for asynchronous transactions,
 306                                 NULL for synchronous transactions
 307   @param[in] RequestPacket      Pointer to an EFI_I2C_REQUEST_PACKET structure
 308                                 describing the I2C transaction
 309   @param[out] I2cStatus         Optional buffer to receive the I2C transaction
 310                                 completion status
 311
 312   @retval EFI_SUCCESS           The asynchronous transaction was successfully
 313                                 queued when Event is not NULL.
 314   @retval EFI_SUCCESS           The transaction completed successfully when
 315                                 Event is NULL.
 316   @retval EFI_ABORTED           The request did not complete because the driver
 317                                 binding Stop() routine was called.
 318   @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is too
 319                                 large.
 320   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the
 321                                 transaction.
 322   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
 323   @retval EFI_NOT_FOUND         Reserved bit set in the SlaveAddress parameter
 324   @retval EFI_NO_MAPPING        The EFI_I2C_HOST_PROTOCOL could not set the
 325                                 bus configuration required to access this I2C
 326                                 device.
 327   @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave
 328                                 address selected by SlaveAddressIndex.
 329                                 EFI_DEVICE_ERROR will be returned if the
 330                                 controller cannot distinguish when the NACK
 331                                 occurred.
 332   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction
 333   @retval EFI_UNSUPPORTED       The controller does not support the requested
 334                                 transaction.
 335
 336 **/
 337 EFI_STATUS
 338 EFIAPI
 339 I2cBusQueueRequest (
 340   IN CONST EFI_I2C_IO_PROTOCOL  *This,
 341   IN UINTN                      SlaveAddressIndex,
 342   IN EFI_EVENT                  Event               OPTIONAL,
 343   IN EFI_I2C_REQUEST_PACKET     *RequestPacket,
 344   OUT EFI_STATUS                *I2cStatus          OPTIONAL
 345   );
 346
 347 /**
 348   Tests to see if this driver supports a given controller. If a child device is provided,
 349   it further tests to see if this driver supports creating a handle for the specified child device.
 350
 351   This function checks to see if the driver specified by This supports the device specified by
 352   ControllerHandle. Drivers will typically use the device path attached to
 353   ControllerHandle and/or the services from the bus I/O abstraction attached to
 354   ControllerHandle to determine if the driver supports ControllerHandle. This function
 355   may be called many times during platform initialization. In order to reduce boot times, the tests
 356   performed by this function must be very small, and take as little time as possible to execute. This
 357   function must not change the state of any hardware devices, and this function must be aware that the
 358   device specified by ControllerHandle may already be managed by the same driver or a
 359   different driver. This function must match its calls to AllocatePages() with FreePages(),
 360   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 361   Since ControllerHandle may have been previously started by the same driver, if a protocol is
 362   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 363   to guarantee the state of ControllerHandle is not modified by this function.
 364
 365   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 366   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 367                                    must support a protocol interface that supplies
 368                                    an I/O abstraction to the driver.
 369   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 370                                    parameter is ignored by device drivers, and is optional for bus
 371                                    drivers. For bus drivers, if this parameter is not NULL, then
 372                                    the bus driver must determine if the bus controller specified
 373                                    by ControllerHandle and the child controller specified
 374                                    by RemainingDevicePath are both supported by this
 375                                    bus driver.
 376
 377   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 378                                    RemainingDevicePath is supported by the driver specified by This.
 379   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 380                                    RemainingDevicePath is already being managed by the driver
 381                                    specified by This.
 382   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 383                                    RemainingDevicePath is already being managed by a different
 384                                    driver or an application that requires exclusive access.
 385                                    Currently not implemented.
 386   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 387                                    RemainingDevicePath is not supported by the driver specified by This.
 388 **/
 389 EFI_STATUS
 390 EFIAPI
 391 I2cBusDriverSupported (
 392   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 393   IN EFI_HANDLE                   Controller,
 394   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 395   );
 396
 397 /**
 398   Starts a device controller or a bus controller.
 399
 400   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 401   As a result, much of the error checking on the parameters to Start() has been moved into this
 402   common boot service. It is legal to call Start() from other locations,
 403   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 404   1. ControllerHandle must be a valid EFI_HANDLE.
 405   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 406      EFI_DEVICE_PATH_PROTOCOL.
 407   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 408      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 409
 410   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 411   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 412                                    must support a protocol interface that supplies
 413                                    an I/O abstraction to the driver.
 414   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 415                                    parameter is ignored by device drivers, and is optional for bus
 416                                    drivers. For a bus driver, if this parameter is NULL, then handles
 417                                    for all the children of Controller are created by this driver.
 418                                    If this parameter is not NULL and the first Device Path Node is
 419                                    not the End of Device Path Node, then only the handle for the
 420                                    child device specified by the first Device Path Node of
 421                                    RemainingDevicePath is created by this driver.
 422                                    If the first Device Path Node of RemainingDevicePath is
 423                                    the End of Device Path Node, no child handle is created by this
 424                                    driver.
 425
 426   @retval EFI_SUCCESS              The device was started.
 427   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 428   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 429   @retval Others                   The driver failded to start the device.
 430
 431 **/
 432 EFI_STATUS
 433 EFIAPI
 434 I2cBusDriverStart (
 435   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 436   IN EFI_HANDLE                   Controller,
 437   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 438   );
 439
 440 /**
 441   Stops a device controller or a bus controller.
 442
 443   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 444   As a result, much of the error checking on the parameters to Stop() has been moved
 445   into this common boot service. It is legal to call Stop() from other locations,
 446   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 447   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 448      same driver's Start() function.
 449   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 450      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 451      Start() function, and the Start() function must have called OpenProtocol() on
 452      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 453
 454   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 455   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 456                                 support a bus specific I/O protocol for the driver
 457                                 to use to stop the device.
 458   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 459   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 460                                 if NumberOfChildren is 0.
 461
 462   @retval EFI_SUCCESS           The device was stopped.
 463   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 464
 465 **/
 466 EFI_STATUS
 467 EFIAPI
 468 I2cBusDriverStop (
 469   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,
 470   IN  EFI_HANDLE                   Controller,
 471   IN  UINTN                        NumberOfChildren,
 472   IN  EFI_HANDLE                   *ChildHandleBuffer
 473   );
 474
 475 /**
 476   Retrieves a Unicode string that is the user readable name of the driver.
 477
 478   This function retrieves the user readable name of a driver in the form of a
 479   Unicode string. If the driver specified by This has a user readable name in
 480   the language specified by Language, then a pointer to the driver name is
 481   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 482   by This does not support the language specified by Language,
 483   then EFI_UNSUPPORTED is returned.
 484
 485   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 486                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 487
 488   @param  Language[in]          A pointer to a Null-terminated ASCII string
 489                                 array indicating the language. This is the
 490                                 language of the driver name that the caller is
 491                                 requesting, and it must match one of the
 492                                 languages specified in SupportedLanguages. The
 493                                 number of languages supported by a driver is up
 494                                 to the driver writer. Language is specified
 495                                 in RFC 4646 or ISO 639-2 language code format.
 496
 497   @param  DriverName[out]       A pointer to the Unicode string to return.
 498                                 This Unicode string is the name of the
 499                                 driver specified by This in the language
 500                                 specified by Language.
 501
 502   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 503                                 This and the language specified by Language was
 504                                 returned in DriverName.
 505
 506   @retval EFI_INVALID_PARAMETER Language is NULL.
 507
 508   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 509
 510   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 511                                 the language specified by Language.
 512
 513 **/
 514 EFI_STATUS
 515 EFIAPI
 516 I2cBusComponentNameGetDriverName (
 517   IN  EFI_COMPONENT_NAME2_PROTOCOL *This,
 518   IN  CHAR8                        *Language,
 519   OUT CHAR16                       **DriverName
 520   );
 521
 522 /**
 523   Retrieves a Unicode string that is the user readable name of the controller
 524   that is being managed by a driver.
 525
 526   This function retrieves the user readable name of the controller specified by
 527   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 528   driver specified by This has a user readable name in the language specified by
 529   Language, then a pointer to the controller name is returned in ControllerName,
 530   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 531   managing the controller specified by ControllerHandle and ChildHandle,
 532   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 533   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 534
 535   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 536                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 537
 538   @param  ControllerHandle[in]  The handle of a controller that the driver
 539                                 specified by This is managing.  This handle
 540                                 specifies the controller whose name is to be
 541                                 returned.
 542
 543   @param  ChildHandle[in]       The handle of the child controller to retrieve
 544                                 the name of.  This is an optional parameter that
 545                                 may be NULL.  It will be NULL for device
 546                                 drivers.  It will also be NULL for a bus drivers
 547                                 that wish to retrieve the name of the bus
 548                                 controller.  It will not be NULL for a bus
 549                                 driver that wishes to retrieve the name of a
 550                                 child controller.
 551
 552   @param  Language[in]          A pointer to a Null-terminated ASCII string
 553                                 array indicating the language.  This is the
 554                                 language of the driver name that the caller is
 555                                 requesting, and it must match one of the
 556                                 languages specified in SupportedLanguages. The
 557                                 number of languages supported by a driver is up
 558                                 to the driver writer. Language is specified in
 559                                 RFC 4646 or ISO 639-2 language code format.
 560
 561   @param  ControllerName[out]   A pointer to the Unicode string to return.
 562                                 This Unicode string is the name of the
 563                                 controller specified by ControllerHandle and
 564                                 ChildHandle in the language specified by
 565                                 Language from the point of view of the driver
 566                                 specified by This.
 567
 568   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 569                                 the language specified by Language for the
 570                                 driver specified by This was returned in
 571                                 DriverName.
 572
 573   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 574
 575   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 576                                 EFI_HANDLE.
 577
 578   @retval EFI_INVALID_PARAMETER Language is NULL.
 579
 580   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 581
 582   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 583                                 managing the controller specified by
 584                                 ControllerHandle and ChildHandle.
 585
 586   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 587                                 the language specified by Language.
 588
 589 **/
 590 EFI_STATUS
 591 EFIAPI
 592 I2cBusComponentNameGetControllerName (
 593   IN  EFI_COMPONENT_NAME2_PROTOCOL                    *This,
 594   IN  EFI_HANDLE                                      ControllerHandle,
 595   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 596   IN  CHAR8                                           *Language,
 597   OUT CHAR16                                          **ControllerName
 598   );
 599
 600 /**
 601   The user entry point for the I2C bus module. The user code starts with
 602   this function.
 603
 604   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
 605   @param[in] SystemTable    A pointer to the EFI System Table.
 606
 607   @retval EFI_SUCCESS       The entry point is executed successfully.
 608   @retval other             Some error occurs when executing this entry point.
 609
 610 **/
 611 EFI_STATUS
 612 EFIAPI
 613 InitializeI2cBus(
 614   IN EFI_HANDLE           ImageHandle,
 615   IN EFI_SYSTEM_TABLE     *SystemTable
 616   );
 617
 618 /**
 619   This is the unload handle for I2C bus module.
 620
 621   Disconnect the driver specified by ImageHandle from all the devices in the handle database.
 622   Uninstall all the protocols installed in the driver entry point.
 623
 624   @param[in] ImageHandle           The drivers' driver image.
 625
 626   @retval    EFI_SUCCESS           The image is unloaded.
 627   @retval    Others                Failed to unload the image.
 628
 629 **/
 630 EFI_STATUS
 631 EFIAPI
 632 I2cBusUnload (
 633   IN EFI_HANDLE             ImageHandle
 634   );
 635
 636 /**
 637   Release all the resources allocated for the I2C device.
 638
 639   This function releases all the resources allocated for the I2C device.
 640
 641   @param  I2cDeviceContext         The I2C child device involved for the operation.
 642
 643 **/
 644 VOID
 645 ReleaseI2cDeviceContext (
 646   IN I2C_DEVICE_CONTEXT          *I2cDeviceContext
 647   );
 648
 649 /**
 650   Complete the current request
 651
 652   @param[in] I2cHost  Address of an I2C_HOST_CONTEXT structure.
 653   @param[in] Status   Status of the I<sub>2</sub>C operation.
 654
 655   @return This routine returns the input status value.
 656
 657 **/
 658 EFI_STATUS
 659 I2cHostRequestComplete (
 660   I2C_HOST_CONTEXT *I2cHost,
 661   EFI_STATUS       Status
 662   );
 663
 664 /**
 665   Enable access to the I2C bus configuration
 666
 667   @param[in] I2cHostContext     Address of an I2C_HOST_CONTEXT structure
 668
 669   @retval EFI_SUCCESS           The operation completed successfully.
 670   @retval EFI_ABORTED           The request did not complete because the driver
 671                                 was shutdown.
 672   @retval EFI_BAD_BUFFER_SIZE   The WriteBytes or ReadBytes buffer size is too large.
 673   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the operation.
 674                                 This could indicate the slave device is not present.
 675   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
 676   @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value
 677   @retval EFI_NO_RESPONSE       The I2C device is not responding to the
 678                                 slave address.  EFI_DEVICE_ERROR may also be
 679                                 returned if the controller can not distinguish
 680                                 when the NACK occurred.
 681   @retval EFI_NOT_FOUND         I2C slave address exceeds maximum address
 682   @retval EFI_NOT_READY         I2C bus is busy or operation pending, wait for
 683                                 the event and then read status.
 684   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C operation
 685   @retval EFI_TIMEOUT           The transaction did not complete within an internally
 686                                 specified timeout period.
 687
 688 **/
 689 EFI_STATUS
 690 I2cHostRequestEnable (
 691   I2C_HOST_CONTEXT *I2cHost
 692   );
 693
 694 /**
 695   Tests to see if this driver supports a given controller. If a child device is provided,
 696   it further tests to see if this driver supports creating a handle for the specified child device.
 697
 698   This function checks to see if the driver specified by This supports the device specified by
 699   ControllerHandle. Drivers will typically use the device path attached to
 700   ControllerHandle and/or the services from the bus I/O abstraction attached to
 701   ControllerHandle to determine if the driver supports ControllerHandle. This function
 702   may be called many times during platform initialization. In order to reduce boot times, the tests
 703   performed by this function must be very small, and take as little time as possible to execute. This
 704   function must not change the state of any hardware devices, and this function must be aware that the
 705   device specified by ControllerHandle may already be managed by the same driver or a
 706   different driver. This function must match its calls to AllocatePages() with FreePages(),
 707   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 708   Since ControllerHandle may have been previously started by the same driver, if a protocol is
 709   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 710   to guarantee the state of ControllerHandle is not modified by this function.
 711
 712   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 713   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 714                                    must support a protocol interface that supplies
 715                                    an I/O abstraction to the driver.
 716   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 717                                    parameter is ignored by device drivers, and is optional for bus
 718                                    drivers. For bus drivers, if this parameter is not NULL, then
 719                                    the bus driver must determine if the bus controller specified
 720                                    by ControllerHandle and the child controller specified
 721                                    by RemainingDevicePath are both supported by this
 722                                    bus driver.
 723
 724   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 725                                    RemainingDevicePath is supported by the driver specified by This.
 726   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 727                                    RemainingDevicePath is already being managed by the driver
 728                                    specified by This.
 729   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 730                                    RemainingDevicePath is already being managed by a different
 731                                    driver or an application that requires exclusive access.
 732                                    Currently not implemented.
 733   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 734                                    RemainingDevicePath is not supported by the driver specified by This.
 735 **/
 736 EFI_STATUS
 737 EFIAPI
 738 I2cHostDriverSupported (
 739   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 740   IN EFI_HANDLE                   Controller,
 741   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 742   );
 743
 744 /**
 745   Starts a device controller or a bus controller.
 746
 747   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 748   As a result, much of the error checking on the parameters to Start() has been moved into this
 749   common boot service. It is legal to call Start() from other locations,
 750   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 751   1. ControllerHandle must be a valid EFI_HANDLE.
 752   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 753      EFI_DEVICE_PATH_PROTOCOL.
 754   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 755      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 756
 757   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 758   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 759                                    must support a protocol interface that supplies
 760                                    an I/O abstraction to the driver.
 761   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 762                                    parameter is ignored by device drivers, and is optional for bus
 763                                    drivers. For a bus driver, if this parameter is NULL, then handles
 764                                    for all the children of Controller are created by this driver.
 765                                    If this parameter is not NULL and the first Device Path Node is
 766                                    not the End of Device Path Node, then only the handle for the
 767                                    child device specified by the first Device Path Node of
 768                                    RemainingDevicePath is created by this driver.
 769                                    If the first Device Path Node of RemainingDevicePath is
 770                                    the End of Device Path Node, no child handle is created by this
 771                                    driver.
 772
 773   @retval EFI_SUCCESS              The device was started.
 774   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 775   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 776   @retval Others                   The driver failded to start the device.
 777
 778 **/
 779 EFI_STATUS
 780 EFIAPI
 781 I2cHostDriverStart (
 782   IN EFI_DRIVER_BINDING_PROTOCOL        *This,
 783   IN EFI_HANDLE                         Controller,
 784   IN EFI_DEVICE_PATH_PROTOCOL           *RemainingDevicePath
 785   );
 786
 787 /**
 788   Stops a device controller or a bus controller.
 789
 790   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 791   As a result, much of the error checking on the parameters to Stop() has been moved
 792   into this common boot service. It is legal to call Stop() from other locations,
 793   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 794   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 795      same driver's Start() function.
 796   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 797      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 798      Start() function, and the Start() function must have called OpenProtocol() on
 799      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 800
 801   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 802   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 803                                 support a bus specific I/O protocol for the driver
 804                                 to use to stop the device.
 805   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 806   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 807                                 if NumberOfChildren is 0.
 808
 809   @retval EFI_SUCCESS           The device was stopped.
 810   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 811
 812 **/
 813 EFI_STATUS
 814 EFIAPI
 815 I2cHostDriverStop (
 816   IN  EFI_DRIVER_BINDING_PROTOCOL       *This,
 817   IN  EFI_HANDLE                        Controller,
 818   IN  UINTN                             NumberOfChildren,
 819   IN  EFI_HANDLE                        *ChildHandleBuffer
 820   );
 821
 822 /**
 823   Retrieves a Unicode string that is the user readable name of the driver.
 824
 825   This function retrieves the user readable name of a driver in the form of a
 826   Unicode string. If the driver specified by This has a user readable name in
 827   the language specified by Language, then a pointer to the driver name is
 828   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 829   by This does not support the language specified by Language,
 830   then EFI_UNSUPPORTED is returned.
 831
 832   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 833                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 834
 835   @param  Language[in]          A pointer to a Null-terminated ASCII string
 836                                 array indicating the language. This is the
 837                                 language of the driver name that the caller is
 838                                 requesting, and it must match one of the
 839                                 languages specified in SupportedLanguages. The
 840                                 number of languages supported by a driver is up
 841                                 to the driver writer. Language is specified
 842                                 in RFC 4646 or ISO 639-2 language code format.
 843
 844   @param  DriverName[out]       A pointer to the Unicode string to return.
 845                                 This Unicode string is the name of the
 846                                 driver specified by This in the language
 847                                 specified by Language.
 848
 849   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 850                                 This and the language specified by Language was
 851                                 returned in DriverName.
 852
 853   @retval EFI_INVALID_PARAMETER Language is NULL.
 854
 855   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 856
 857   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 858                                 the language specified by Language.
 859
 860 **/
 861 EFI_STATUS
 862 EFIAPI
 863 I2cHostComponentNameGetDriverName (
 864   IN  EFI_COMPONENT_NAME2_PROTOCOL *This,
 865   IN  CHAR8                        *Language,
 866   OUT CHAR16                       **DriverName
 867   );
 868
 869 /**
 870   Retrieves a Unicode string that is the user readable name of the controller
 871   that is being managed by a driver.
 872
 873   This function retrieves the user readable name of the controller specified by
 874   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 875   driver specified by This has a user readable name in the language specified by
 876   Language, then a pointer to the controller name is returned in ControllerName,
 877   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 878   managing the controller specified by ControllerHandle and ChildHandle,
 879   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 880   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 881
 882   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 883                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 884
 885   @param  ControllerHandle[in]  The handle of a controller that the driver
 886                                 specified by This is managing.  This handle
 887                                 specifies the controller whose name is to be
 888                                 returned.
 889
 890   @param  ChildHandle[in]       The handle of the child controller to retrieve
 891                                 the name of.  This is an optional parameter that
 892                                 may be NULL.  It will be NULL for device
 893                                 drivers.  It will also be NULL for a bus drivers
 894                                 that wish to retrieve the name of the bus
 895                                 controller.  It will not be NULL for a bus
 896                                 driver that wishes to retrieve the name of a
 897                                 child controller.
 898
 899   @param  Language[in]          A pointer to a Null-terminated ASCII string
 900                                 array indicating the language.  This is the
 901                                 language of the driver name that the caller is
 902                                 requesting, and it must match one of the
 903                                 languages specified in SupportedLanguages. The
 904                                 number of languages supported by a driver is up
 905                                 to the driver writer. Language is specified in
 906                                 RFC 4646 or ISO 639-2 language code format.
 907
 908   @param  ControllerName[out]   A pointer to the Unicode string to return.
 909                                 This Unicode string is the name of the
 910                                 controller specified by ControllerHandle and
 911                                 ChildHandle in the language specified by
 912                                 Language from the point of view of the driver
 913                                 specified by This.
 914
 915   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 916                                 the language specified by Language for the
 917                                 driver specified by This was returned in
 918                                 DriverName.
 919
 920   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 921
 922   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 923                                 EFI_HANDLE.
 924
 925   @retval EFI_INVALID_PARAMETER Language is NULL.
 926
 927   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 928
 929   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 930                                 managing the controller specified by
 931                                 ControllerHandle and ChildHandle.
 932
 933   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 934                                 the language specified by Language.
 935
 936 **/
 937 EFI_STATUS
 938 EFIAPI
 939 I2cHostComponentNameGetControllerName (
 940   IN  EFI_COMPONENT_NAME2_PROTOCOL                    *This,
 941   IN  EFI_HANDLE                                      ControllerHandle,
 942   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 943   IN  CHAR8                                           *Language,
 944   OUT CHAR16                                          **ControllerName
 945   );
 946
 947 /**
 948   Handle the bus available event
 949
 950   This routine is called at TPL_I2C_SYNC.
 951
 952   @param[in] Event    Address of an EFI_EVENT handle
 953   @param[in] Context  Address of an I2C_HOST_CONTEXT structure
 954
 955 **/
 956 VOID
 957 EFIAPI
 958 I2cHostRequestCompleteEvent (
 959   IN EFI_EVENT Event,
 960   IN VOID *Context
 961   );
 962
 963 /**
 964   Handle the I2C bus configuration available event
 965
 966   This routine is called at TPL_I2C_SYNC.
 967
 968   @param[in] Event    Address of an EFI_EVENT handle
 969   @param[in] Context  Address of an I2C_HOST_CONTEXT structure
 970
 971 **/
 972 VOID
 973 EFIAPI
 974 I2cHostI2cBusConfigurationAvailable (
 975   IN EFI_EVENT Event,
 976   IN VOID *Context
 977   );
 978
 979 /**
 980   Queue an I2C operation for execution on the I2C controller.
 981
 982   This routine must be called at or below TPL_NOTIFY.  For synchronous
 983   requests this routine must be called at or below TPL_CALLBACK.
 984
 985   N.B. The typical consumers of this API are the I2C bus driver and
 986   on rare occasions the I2C test application.  Extreme care must be
 987   taken by other consumers of this API to prevent confusing the
 988   third party I2C drivers due to a state change at the I2C device
 989   which the third party I2C drivers did not initiate.  I2C platform
 990   drivers may use this API within these guidelines.
 991
 992   This layer uses the concept of I2C bus configurations to describe
 993   the I2C bus.  An I2C bus configuration is defined as a unique
 994   setting of the multiplexers and switches in the I2C bus which
 995   enable access to one or more I2C devices.  When using a switch
 996   to divide a bus, due to speed differences, the I2C platform layer
 997   would define an I2C bus configuration for the I2C devices on each
 998   side of the switch.  When using a multiplexer, the I2C platform
 999   layer defines an I2C bus configuration for each of the selector
1000   values required to control the multiplexer.  See Figure 1 in the
1001   <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C
1002   Specification</a> for a complex I2C bus configuration.
1003
1004   The I2C host driver processes all operations in FIFO order.  Prior to
1005   performing the operation, the I2C host driver calls the I2C platform
1006   driver to reconfigure the switches and multiplexers in the I2C bus
1007   enabling access to the specified I2C device.  The I2C platform driver
1008   also selects the maximum bus speed for the device.  After the I2C bus
1009   is configured, the I2C host driver calls the I2C port driver to
1010   initialize the I2C controller and start the I2C operation.
1011
1012   @param[in] This             Address of an EFI_I2C_HOST_PROTOCOL instance.
1013   @param[in] I2cBusConfiguration  I2C bus configuration to access the I2C
1014                                   device.
1015   @param[in] SlaveAddress     Address of the device on the I2C bus.
1016   @param[in] Event            Event to set for asynchronous operations,
1017                               NULL for synchronous operations
1018   @param[in] RequestPacket    Address of an EFI_I2C_REQUEST_PACKET
1019                               structure describing the I2C operation
1020   @param[out] I2cStatus       Optional buffer to receive the I2C operation
1021                               completion status
1022
1023   @retval EFI_SUCCESS           The operation completed successfully.
1024   @retval EFI_ABORTED           The request did not complete because the driver
1025                                 was shutdown.
1026   @retval EFI_BAD_BUFFER_SIZE   The WriteBytes or ReadBytes buffer size is too large.
1027   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the operation.
1028                                 This could indicate the slave device is not present.
1029   @retval EFI_INVALID_PARAMETER RequestPacket is NULL
1030   @retval EFI_INVALID_PARAMETER TPL is too high
1031   @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value
1032   @retval EFI_NO_RESPONSE       The I2C device is not responding to the
1033                                 slave address.  EFI_DEVICE_ERROR may also be
1034                                 returned if the controller can not distinguish
1035                                 when the NACK occurred.
1036   @retval EFI_NOT_FOUND         I2C slave address exceeds maximum address
1037   @retval EFI_NOT_READY         I2C bus is busy or operation pending, wait for
1038                                 the event and then read status pointed to by
1039                                 the request packet.
1040   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C operation
1041   @retval EFI_TIMEOUT           The transaction did not complete within an internally
1042                                 specified timeout period.
1043
1044 **/
1045 EFI_STATUS
1046 EFIAPI
1047 I2cHostQueueRequest (
1048   IN CONST EFI_I2C_HOST_PROTOCOL  *This,
1049   IN UINTN                        I2cBusConfiguration,
1050   IN UINTN                        SlaveAddress,
1051   IN EFI_EVENT                    Event            OPTIONAL,
1052   IN EFI_I2C_REQUEST_PACKET       *RequestPacket,
1053   OUT EFI_STATUS                  *I2cStatus       OPTIONAL
1054   );
1055
1056 /**
1057   The user Entry Point for I2C host module. The user code starts with this function.
1058
1059   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
1060   @param[in] SystemTable    A pointer to the EFI System Table.
1061
1062   @retval EFI_SUCCESS       The entry point is executed successfully.
1063   @retval other             Some error occurs when executing this entry point.
1064
1065 **/
1066 EFI_STATUS
1067 EFIAPI
1068 InitializeI2cHost(
1069   IN EFI_HANDLE           ImageHandle,
1070   IN EFI_SYSTEM_TABLE     *SystemTable
1071   );
1072
1073 /**
1074   This is the unload handle for I2C host module.
1075
1076   Disconnect the driver specified by ImageHandle from all the devices in the handle database.
1077   Uninstall all the protocols installed in the driver entry point.
1078
1079   @param[in] ImageHandle           The drivers' driver image.
1080
1081   @retval    EFI_SUCCESS           The image is unloaded.
1082   @retval    Others                Failed to unload the image.
1083
1084 **/
1085 EFI_STATUS
1086 EFIAPI
1087 I2cHostUnload (
1088   IN EFI_HANDLE             ImageHandle
1089   );
1090
1091 #endif  //  __I2C_DXE_H__