Committing changes to the comments, after review with engineers.

[mirror_edk2.git] / IntelFrameworkModulePkg / Include / Protocol / VgaMiniPort.h

diff --git a/IntelFrameworkModulePkg/Include/Protocol/VgaMiniPort.h b/IntelFrameworkModulePkg/Include/Protocol/VgaMiniPort.h
index 714028993cbe13664ef854b730df505d16cb51d1..d5ee730aad7207c03ba44c5af7199355044366e5 100644 (file)
--- a/IntelFrameworkModulePkg/Include/Protocol/VgaMiniPort.h
+++ b/IntelFrameworkModulePkg/Include/Protocol/VgaMiniPort.h
@@ -1,55 +1,91 @@
-/**@file\r
-  Vga Mini port binding for a VGA controller\r
-\r
-Copyright (c) 2006 - 2007, 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
+/** @file\r
+  VGA Mini Port Protocol that is used to set the text display mode of a VGA controller.\r
+\r
+  Copyright (c) 2006 - 2009, 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 __VGA_MINI_PORT_H_\r
 #define __VGA_MINI_PORT_H_\r
 \r
+///\r
+/// Global ID for the EFI_VGA_MINI_PORT_PROTOCOL\r
+///\r
 #define EFI_VGA_MINI_PORT_PROTOCOL_GUID \\r
   { \\r
     0xc7735a2f, 0x88f5, 0x4882, {0xae, 0x63, 0xfa, 0xac, 0x8c, 0x8b, 0x86, 0xb3 } \\r
   }\r
 \r
+///\r
+/// Forward declaration for the EFI_VGA_MINI_PORT_PROTOCOL\r
+///\r
 typedef struct _EFI_VGA_MINI_PORT_PROTOCOL  EFI_VGA_MINI_PORT_PROTOCOL;\r
 \r
 /**\r
-  Sets the text display mode of a VGA controller\r
+  Sets the text display mode of a VGA controller.\r
   \r
-  @param This             Protocol instance pointer.\r
-  @param Mode             Mode number.  0 - 80x25   1-80x50\r
+  Sets the text display mode of the VGA controller to the mode specified by \r
+  ModeNumber.  A ModeNumber of 0 is a request for an 80x25 text mode.  A \r
+  ModeNumber of 1 is a request for an 80x50 text mode.  If ModeNumber is greater\r
+  than MaxModeNumber, then EFI_UNSUPPORTED is returned.  If the VGA controller \r
+  is not functioning properly, then EFI_DEVICE_ERROR is returned.  If the VGA\r
+  controller is sucessfully set to the mode number specified by ModeNumber, then \r
+  EFI_SUCCESS is returned.\r
+    \r
+  @param[in] This         A pointer to the EFI_VGA_MINI_PORT_PROTOCOL instance.\r
+  @param[in] ModeNumber   The requested mode number.  0 for 80x25.  1 for 80x5.\r
 \r
-  @retval EFI_SUCCESS            The mode was set\r
-  @retval EFI_DEVICE_ERROR       The device is not functioning properly.\r
+  @retval EFI_SUCCESS        The mode number was set\r
+  @retval EFI_UNSUPPORTED    The mode number specified by ModeNumber is not supported.\r
+  @retval EFI_DEVICE_ERROR   The device is not functioning properly.\r
   \r
 **/\r
 typedef\r
 EFI_STATUS\r
-(EFIAPI *EFI_VGA_MINI_PORT_SET_MODE) (\r
-  IN EFI_VGA_MINI_PORT_PROTOCOL          * This,\r
-  IN UINTN                               ModeNumber\r
+(EFIAPI *EFI_VGA_MINI_PORT_SET_MODE)(\r
+  IN EFI_VGA_MINI_PORT_PROTOCOL  *This,\r
+  IN UINTN                        ModeNumber\r
   );\r
 \r
 struct _EFI_VGA_MINI_PORT_PROTOCOL {\r
   EFI_VGA_MINI_PORT_SET_MODE  SetMode;\r
-\r
+  ///\r
+  /// MMIO base address of the VGA text mode framebuffer.  Typically set to 0xB8000.\r
+  ///\r
   UINT64                      VgaMemoryOffset;\r
+  ///\r
+  /// I/O Port address for the VGA CRTC address register. Typically set to 0x3D4.\r
+  ///\r
   UINT64                      CrtcAddressRegisterOffset;\r
+  ///\r
+  /// I/O Port address for the VGA CRTC data register.  Typically set to 0x3D5.\r
+  ///\r
   UINT64                      CrtcDataRegisterOffset;\r
-\r
+  ///\r
+  /// PCI Controller MMIO BAR index of the VGA text mode frame buffer.  Typically \r
+  /// set to EFI_PCI_IO_PASS_THROUGH_BAR\r
+  ///\r
   UINT8                       VgaMemoryBar;\r
+  ///\r
+  /// PCI Controller I/O BAR index of the VGA CRTC address register.  Typically \r
+  /// set to EFI_PCI_IO_PASS_THROUGH_BAR\r
+  ///\r
   UINT8                       CrtcAddressRegisterBar;\r
+  ///\r
+  /// PCI Controller I/O BAR index of the VGA CRTC data register.  Typically set \r
+  /// to EFI_PCI_IO_PASS_THROUGH_BAR\r
+  ///\r
   UINT8                       CrtcDataRegisterBar;\r
-\r
+  ///\r
+  /// The maximum number of text modes that this VGA controller supports.\r
+  ///\r
   UINT8                       MaxMode;\r
 };\r
 \r