Add ASSERT() check for StringInfo pointer.

[mirror_edk2.git] / MdeModulePkg / Bus / Usb / UsbKbDxe / KeyBoard.h

/** @file\r
  Function prototype for USB Keyboard Driver.\r
\r
Copyright (c) 2004 - 2008, Intel Corporation\r
All rights reserved. This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef _EFI_KEYBOARD_H_\r
#define _EFI_KEYBOARD_H_\r
\r
\r
#include "EfiKey.h"\r
\r
/**\r
  Uses USB I/O to check whether the device is a USB keyboard device.\r
\r
  @param  UsbIo    Pointer to a USB I/O protocol instance.\r
\r
  @retval TRUE     Device is a USB keyboard device.\r
  @retval FALSE    Device is a not USB keyboard device.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
IsUSBKeyboard (\r
  IN  EFI_USB_IO_PROTOCOL       *UsbIo\r
  );\r
\r
/**\r
  Initialize USB keyboard device and all private data structures.\r
\r
  @param  UsbKeyboardDevice  The USB_KB_DEV instance.\r
\r
  @retval EFI_SUCCESS        Initialization is successful.\r
  @retval EFI_DEVICE_ERROR   Keyboard initialization failed.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
InitUSBKeyboard (\r
  IN OUT USB_KB_DEV   *UsbKeyboardDevice\r
  );\r
\r
/**\r
  Initialize USB keyboard layout.\r
\r
  This function initializes Key Convertion Table for the USB keyboard device.\r
  It first tries to retrieve layout from HII database. If failed and default\r
  layout is enabled, then it just uses the default layout.\r
\r
  @param  UsbKeyboardDevice      The USB_KB_DEV instance.\r
\r
  @retval EFI_SUCCESS            Initialization succeeded.\r
  @retval EFI_NOT_READY          Keyboard layout cannot be retrieve from HII\r
                                 database, and default layout is disabled.\r
  @retval Other                  Fail to register event to EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID group.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
InitKeyboardLayout (\r
  OUT USB_KB_DEV   *UsbKeyboardDevice\r
  );\r
\r
/**\r
  Destroy resources for keyboard layout.\r
\r
  @param  UsbKeyboardDevice    The USB_KB_DEV instance.\r
\r
**/\r
VOID\r
EFIAPI\r
ReleaseKeyboardLayoutResources (\r
  IN OUT USB_KB_DEV              *UsbKeyboardDevice\r
  );\r
\r
/**\r
  Handler function for USB keyboard's asynchronous interrupt transfer.\r
\r
  This function is the handler function for USB keyboard's asynchronous interrupt transfer\r
  to manage the keyboard. It parses the USB keyboard input report, and inserts data to\r
  keyboard buffer according to state of modifer keys and normal keys. Timer for repeat key\r
  is also set accordingly.\r
\r
  @param  Data             A pointer to a buffer that is filled with key data which is\r
                           retrieved via asynchronous interrupt transfer.\r
  @param  DataLength       Indicates the size of the data buffer.\r
  @param  Context          Pointing to USB_KB_DEV instance.\r
  @param  Result           Indicates the result of the asynchronous interrupt transfer.\r
\r
  @retval EFI_SUCCESS      Asynchronous interrupt transfer is handled successfully.\r
  @retval EFI_DEVICE_ERROR Hardware error occurs.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
KeyboardHandler (\r
  IN  VOID          *Data,\r
  IN  UINTN         DataLength,\r
  IN  VOID          *Context,\r
  IN  UINT32        Result\r
  );\r
\r
/**\r
  Handler for Delayed Recovery event.\r
\r
  This function is the handler for Delayed Recovery event triggered\r
  by timer.\r
  After a device error occurs, the event would be triggered\r
  with interval of EFI_USB_INTERRUPT_DELAY. EFI_USB_INTERRUPT_DELAY\r
  is defined in USB standard for error handling.\r
\r
  @param  Event              The Delayed Recovery event.\r
  @param  Context            Points to the USB_KB_DEV instance.\r
\r
**/\r
VOID\r
EFIAPI\r
USBKeyboardRecoveryHandler (\r
  IN    EFI_EVENT    Event,\r
  IN    VOID         *Context\r
  );\r
\r
/**\r
  Retrieves a USB keycode after parsing the raw data in keyboard buffer.\r
\r
  This function parses keyboard buffer. It updates state of modifier key for\r
  USB_KB_DEV instancem, and returns keycode for output.\r
\r
  @param  UsbKeyboardDevice    The USB_KB_DEV instance.\r
  @param  KeyCode              Pointer to the USB keycode for output.\r
\r
  @retval EFI_SUCCESS          Keycode successfully parsed.\r
  @retval EFI_NOT_READY        Keyboard buffer is not ready for a valid keycode\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
USBParseKey (\r
  IN OUT  USB_KB_DEV  *UsbKeyboardDevice,\r
  OUT     UINT8       *KeyCode\r
  );\r
\r
/**\r
  Converts USB Keycode ranging from 0x4 to 0x65 to EFI_INPUT_KEY.\r
\r
  @param  UsbKeyboardDevice     The USB_KB_DEV instance.\r
  @param  KeyCode               Indicates the key code that will be interpreted.\r
  @param  Key                   A pointer to a buffer that is filled in with\r
                                the keystroke information for the key that\r
                                was pressed.\r
\r
  @retval EFI_SUCCESS           Success.\r
  @retval EFI_INVALID_PARAMETER KeyCode is not in the range of 0x4 to 0x65.\r
  @retval EFI_INVALID_PARAMETER Translated EFI_INPUT_KEY has zero for both ScanCode and UnicodeChar.\r
  @retval EFI_NOT_READY         KeyCode represents a dead key with EFI_NS_KEY_MODIFIER\r
  @retval EFI_DEVICE_ERROR      Keyboard layout is invalid.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
UsbKeyCodeToEfiInputKey (\r
  IN  USB_KB_DEV      *UsbKeyboardDevice,\r
  IN  UINT8           KeyCode,\r
  OUT EFI_INPUT_KEY   *Key\r
  );\r
\r
/**\r
  Resets USB keyboard buffer.\r
\r
  @param  KeyboardBuffer     Points to the USB keyboard buffer.\r
\r
**/\r
VOID\r
EFIAPI\r
InitUSBKeyBuffer (\r
  OUT  USB_KB_BUFFER   *KeyboardBuffer\r
  );\r
\r
/**\r
  Check whether USB keyboard buffer is empty.\r
\r
  @param  KeyboardBuffer     USB keyboard buffer\r
\r
  @retval TRUE               Keyboard buffer is empty.\r
  @retval FALSE              Keyboard buffer is not empty.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
IsUSBKeyboardBufferEmpty (\r
  IN  USB_KB_BUFFER   *KeyboardBuffer\r
  );\r
\r
/**\r
  Check whether USB keyboard buffer is full.\r
\r
  @param  KeyboardBuffer     USB keyboard buffer\r
\r
  @retval TRUE               Keyboard buffer is full.\r
  @retval FALSE              Keyboard buffer is not full.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
IsUSBKeyboardBufferFull (\r
  IN  USB_KB_BUFFER   *KeyboardBuffer\r
  );\r
\r
/**\r
  Inserts a keycode into keyboard buffer.\r
\r
  @param  KeyboardBuffer     Points to the USB keyboard buffer.\r
  @param  Key                Keycode to insert.\r
  @param  Down               TRUE means key is pressed.\r
                             FALSE means key is released.\r
\r
**/\r
VOID\r
EFIAPI\r
InsertKeyCode (\r
  IN OUT  USB_KB_BUFFER *KeyboardBuffer,\r
  IN      UINT8         Key,\r
  IN      BOOLEAN       Down\r
  );\r
\r
/**\r
  Remove a keycode from keyboard buffer and return it.\r
\r
  @param  KeyboardBuffer     Points to the USB keyboard buffer.\r
  @param  UsbKey             Points to the buffer that contains keycode for output.\r
\r
  @retval EFI_SUCCESS        Keycode successfully removed from keyboard buffer.\r
  @retval EFI_DEVICE_ERROR   Keyboard buffer is empty.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
RemoveKeyCode (\r
  IN OUT  USB_KB_BUFFER *KeyboardBuffer,\r
     OUT  USB_KEY       *UsbKey\r
  );\r
\r
/**\r
  Handler for Repeat Key event.\r
\r
  This function is the handler for Repeat Key event triggered\r
  by timer.\r
  After a repeatable key is pressed, the event would be triggered\r
  with interval of USBKBD_REPEAT_DELAY. Once the event is triggered,\r
  following trigger will come with interval of USBKBD_REPEAT_RATE.\r
\r
  @param  Event              The Repeat Key event.\r
  @param  Context            Points to the USB_KB_DEV instance.\r
\r
**/\r
VOID\r
EFIAPI\r
USBKeyboardRepeatHandler (\r
  IN    EFI_EVENT    Event,\r
  IN    VOID         *Context\r
  );\r
\r
/**\r
  Sets USB keyboard LED state.\r
\r
  @param  UsbKeyboardDevice  The USB_KB_DEV instance.\r
\r
**/\r
VOID\r
EFIAPI\r
SetKeyLED (\r
  IN  USB_KB_DEV    *UsbKeyboardDevice\r
  );\r
\r
#endif\r