ArmPlatformPkg: Tidy Lcd code: Updated comments

There is no functional modification in this change
some comments are modified and a few new comments are added.
This is to prevent mixing formatting changes with functional
changes.

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Girish Pathak <girish.pathak@arm.com>
Signed-off-by: Evan Lloyd <evan.lloyd@arm.com>
Reviewed-by: Leif Lindholm <leif.lindholm@linaro.org>

diff --git a/ArmPlatformPkg/Drivers/LcdGraphicsOutputDxe/LcdGraphicsOutputDxe.c b/ArmPlatformPkg/Drivers/LcdGraphicsOutputDxe/LcdGraphicsOutputDxe.c
index 905eb26ee01b5037dfbaf3c054a62593837c8b5f..872361cd23fbdf52c5f128d0e172701e76d832b2 100644 (file)
--- a/ArmPlatformPkg/Drivers/LcdGraphicsOutputDxe/LcdGraphicsOutputDxe.c
+++ b/ArmPlatformPkg/Drivers/LcdGraphicsOutputDxe/LcdGraphicsOutputDxe.c
@@ -1,13 +1,14 @@
 /** @file\r
+  This file implements the Graphics Output protocol for Arm platforms\r
 \r
- Copyright (c) 2011-2018, ARM Ltd. All rights reserved.<BR>\r
- 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
+  Copyright (c) 2011-2018, ARM Ltd. All rights reserved.<BR>\r
+  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
+  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
@@ -22,11 +23,6 @@
 \r
 #include "LcdGraphicsOutputDxe.h"\r
 \r
-/** This file implements the Graphics Output protocol on ArmVersatileExpress\r
-  using the Lcd controller\r
-\r
-**/\r
-\r
 //\r
 // Global variables\r
 //\r

diff --git a/ArmPlatformPkg/Include/Library/LcdPlatformLib.h b/ArmPlatformPkg/Include/Library/LcdPlatformLib.h
index 3d13e417972c67cc51ae4410efd548053511e5d1..e51e78640ae7b1acd51ac333ba3faa8c78aea5a5 100644 (file)
--- a/ArmPlatformPkg/Include/Library/LcdPlatformLib.h
+++ b/ArmPlatformPkg/Include/Library/LcdPlatformLib.h
@@ -18,9 +18,7 @@
 \r
 #define LCD_VRAM_SIZE                     SIZE_8MB\r
 \r
-//\r
 // Modes definitions\r
-//\r
 #define VGA                               0\r
 #define SVGA                              1\r
 #define XGA                               2\r
@@ -29,9 +27,7 @@
 #define UXGA                              5\r
 #define HD                                6\r
 \r
-//\r
 // VGA Mode: 640 x 480\r
-//\r
 #define VGA_H_RES_PIXELS                  640\r
 #define VGA_V_RES_PIXELS                  480\r
 #define VGA_OSC_FREQUENCY                 23750000  /* 0x016A6570 */\r
@@ -44,9 +40,7 @@
 #define VGA_V_FRONT_PORCH                 (  3 - 1)\r
 #define VGA_V_BACK_PORCH                  ( 13 - 1)\r
 \r
-//\r
 // SVGA Mode: 800 x 600\r
-//\r
 #define SVGA_H_RES_PIXELS                 800\r
 #define SVGA_V_RES_PIXELS                 600\r
 #define SVGA_OSC_FREQUENCY                38250000  /* 0x0247A610 */\r
@@ -59,9 +53,7 @@
 #define SVGA_V_FRONT_PORCH                (  3 - 1)\r
 #define SVGA_V_BACK_PORCH                 ( 17 - 1)\r
 \r
-//\r
 // XGA Mode: 1024 x 768\r
-//\r
 #define XGA_H_RES_PIXELS                  1024\r
 #define XGA_V_RES_PIXELS                  768\r
 #define XGA_OSC_FREQUENCY                 63500000  /* 0x03C8EEE0 */\r
@@ -74,9 +66,7 @@
 #define XGA_V_FRONT_PORCH                 (  3 - 1)\r
 #define XGA_V_BACK_PORCH                  ( 23 - 1)\r
 \r
-//\r
 // SXGA Mode: 1280 x 1024\r
-//\r
 #define SXGA_H_RES_PIXELS                 1280\r
 #define SXGA_V_RES_PIXELS                 1024\r
 #define SXGA_OSC_FREQUENCY                109000000  /* 0x067F3540 */\r
@@ -89,9 +79,7 @@
 #define SXGA_V_FRONT_PORCH                (  3 - 1)\r
 #define SXGA_V_BACK_PORCH                 ( 29 - 1)\r
 \r
-//\r
 // WSXGA+ Mode: 1680 x 1050\r
-//\r
 #define WSXGA_H_RES_PIXELS                1680\r
 #define WSXGA_V_RES_PIXELS                1050\r
 #define WSXGA_OSC_FREQUENCY               147000000  /* 0x08C30AC0 */\r
@@ -104,9 +92,7 @@
 #define WSXGA_V_FRONT_PORCH               (  4 - 1)\r
 #define WSXGA_V_BACK_PORCH                ( 41 - 1)\r
 \r
-//\r
 // UXGA Mode: 1600 x 1200\r
-//\r
 #define UXGA_H_RES_PIXELS                 1600\r
 #define UXGA_V_RES_PIXELS                 1200\r
 #define UXGA_OSC_FREQUENCY                161000000  /* 0x0998AA40 */\r
@@ -119,9 +105,7 @@
 #define UXGA_V_FRONT_PORCH                (  3 - 1)\r
 #define UXGA_V_BACK_PORCH                 ( 38 - 1)\r
 \r
-//\r
 // HD Mode: 1920 x 1080\r
-//\r
 #define HD_H_RES_PIXELS                   1920\r
 #define HD_V_RES_PIXELS                   1080\r
 #define HD_OSC_FREQUENCY                  165000000  /* 0x09D5B340 */\r
@@ -134,10 +118,7 @@
 #define HD_V_FRONT_PORCH                  (  3 - 1)\r
 #define HD_V_BACK_PORCH                   ( 32 - 1)\r
 \r
-//\r
 // Colour Masks\r
-//\r
-\r
 #define LCD_24BPP_RED_MASK              0x00FF0000\r
 #define LCD_24BPP_GREEN_MASK            0x0000FF00\r
 #define LCD_24BPP_BLUE_MASK             0x000000FF\r
@@ -158,7 +139,7 @@
 #define LCD_12BPP_444_BLUE_MASK         0x0000000F\r
 #define LCD_12BPP_444_RESERVED_MASK     0x0000F000\r
 \r
-/** The enumeration indexes maps the PL111 LcdBpp values used in the LCD Control\r
+/** The enumeration maps the PL111 LcdBpp values used in the LCD Control\r
   Register\r
 **/\r
 typedef enum {\r
@@ -172,33 +153,94 @@ typedef enum {
   LCD_BITS_PER_PIXEL_12_444\r
 } LCD_BPP;\r
 \r
+/** Platform related initialization function.\r
+\r
+  @param[in] Handle              Handle to the LCD device instance.\r
+\r
+  @retval EFI_SUCCESS            Plaform library initialized successfully.\r
+  @retval !(EFI_SUCCESS)         Other errors.\r
+**/\r
 EFI_STATUS\r
 LcdPlatformInitializeDisplay (\r
   IN EFI_HANDLE   Handle\r
   );\r
 \r
+/** Allocate VRAM memory in DRAM for the framebuffer\r
+  (unless it is reserved already).\r
+\r
+  The allocated address can be used to set the framebuffer.\r
+\r
+  @param[out] VramBaseAddress      A pointer to the framebuffer address.\r
+  @param[out] VramSize             A pointer to the size of the frame\r
+                                   buffer in bytes\r
+\r
+  @retval EFI_SUCCESS              Frame buffer memory allocated successfully.\r
+  @retval !(EFI_SUCCESS)           Other errors.\r
+**/\r
 EFI_STATUS\r
 LcdPlatformGetVram (\r
   OUT EFI_PHYSICAL_ADDRESS*                 VramBaseAddress,\r
   OUT UINTN*                                VramSize\r
   );\r
 \r
+/** Return total number of modes supported.\r
+\r
+  Note: Valid mode numbers are 0 to MaxMode - 1\r
+  See Section 12.9 of the UEFI Specification 2.7\r
+\r
+  @retval UINT32             Mode Number.\r
+**/\r
 UINT32\r
 LcdPlatformGetMaxMode (\r
   VOID\r
   );\r
 \r
+/** Set the requested display mode.\r
+\r
+  @param[in] ModeNumber            Mode Number.\r
+\r
+  @retval  EFI_SUCCESS             Mode set successfully.\r
+  @retval  EFI_INVALID_PARAMETER   Requested mode not found.\r
+  @retval  !(EFI_SUCCESS)          Other errors.\r
+**/\r
 EFI_STATUS\r
 LcdPlatformSetMode (\r
   IN UINT32                                 ModeNumber\r
   );\r
 \r
+/** Return information for the requested mode number.\r
+\r
+  @param[in]  ModeNumber         Mode Number.\r
+  @param[out] Info               Pointer for returned mode information\r
+                                 (on success).\r
+\r
+  @retval EFI_SUCCESS             Mode information for the requested mode\r
+                                  returned successfully.\r
+  @retval EFI_INVALID_PARAMETER   Requested mode not found.\r
+**/\r
 EFI_STATUS\r
 LcdPlatformQueryMode (\r
   IN  UINT32                                ModeNumber,\r
   OUT EFI_GRAPHICS_OUTPUT_MODE_INFORMATION  *Info\r
   );\r
 \r
+/** Return display timing information for the requested mode number.\r
+\r
+  @param[in]  ModeNumber          Mode Number.\r
+\r
+  @param[out] HRes                Pointer to horizontal resolution.\r
+  @param[out] HSync               Pointer to horizontal sync width.\r
+  @param[out] HBackPorch          Pointer to horizontal back porch.\r
+  @param[out] HFrontPorch         Pointer to horizontal front porch.\r
+  @param[out] VRes                Pointer to vertical resolution.\r
+  @param[out] VSync               Pointer to vertical sync width.\r
+  @param[out] VBackPorch          Pointer to vertical back porch.\r
+  @param[out] VFrontPorch         Pointer to vertical front porch.\r
+\r
+  @retval EFI_SUCCESS             Display timing information for the requested\r
+                                  mode returned successfully.\r
+  @retval EFI_INVALID_PARAMETER   Requested mode not found.\r
+**/\r
 EFI_STATUS\r
 LcdPlatformGetTimings (\r
   IN  UINT32                              ModeNumber,\r
@@ -212,6 +254,16 @@ LcdPlatformGetTimings (
   OUT UINT32*                             VFrontPorch\r
   );\r
 \r
+/** Return bits per pixel information for a mode number.\r
+\r
+  @param[in]  ModeNumber          Mode Number.\r
+\r
+  @param[out] Bpp                 Pointer to value bits per pixel information.\r
+\r
+  @retval EFI_SUCCESS             Bit per pixel information for the requested\r
+                                  mode returned successfully.\r
+  @retval EFI_INVALID_PARAMETER   Requested mode not found.\r
+**/\r
 EFI_STATUS\r
 LcdPlatformGetBpp (\r
   IN  UINT32                                ModeNumber,\r

diff --git a/ArmPlatformPkg/Library/HdLcd/HdLcd.c b/ArmPlatformPkg/Library/HdLcd/HdLcd.c
index 2cd1be9d255dd5734176d752d60f06f11a047fcb..be4ccfdc1f421060faec792c8e8acfcfb3232014 100644 (file)
--- a/ArmPlatformPkg/Library/HdLcd/HdLcd.c
+++ b/ArmPlatformPkg/Library/HdLcd/HdLcd.c
@@ -1,4 +1,5 @@
 /** @file\r
+  This file contains the platform independent parts of HdLcd\r
 \r
   Copyright (c) 2011-2018, ARM Ltd. All rights reserved.<BR>\r
 \r
@@ -21,10 +22,6 @@
 \r
 #include "HdLcd.h"\r
 \r
-/** This file contains all the bits of the Lcd that are\r
-  platform independent.\r
-**/\r
-\r
 STATIC\r
 UINTN\r
 GetBytesPerPixel (\r
@@ -51,6 +48,12 @@ GetBytesPerPixel (
   }\r
 }\r
 \r
+/** Initialize display.\r
+\r
+  @param[in]  VramBaseAddress    Address of the framebuffer.\r
+\r
+  @retval EFI_SUCCESS            Display initialization successful.\r
+**/\r
 EFI_STATUS\r
 LcdInitialize (\r
   IN EFI_PHYSICAL_ADDRESS   VramBaseAddress\r
@@ -82,6 +85,14 @@ LcdInitialize (
   return EFI_SUCCESS;\r
 }\r
 \r
+/** Set requested mode of the display.\r
+\r
+  @param[in] ModeNumber          Display mode number.\r
+\r
+  @retval EFI_SUCCESS            Display mode set successfully.\r
+  @retval EFI_DEVICE_ERROR       Reurns an error if display timing\r
+                                 information is not available.\r
+**/\r
 EFI_STATUS\r
 LcdSetMode (\r
   IN UINT32  ModeNumber\r
@@ -150,6 +161,8 @@ LcdSetMode (
   return EFI_SUCCESS;\r
 }\r
 \r
+/** De-initializes the display.\r
+**/\r
 VOID\r
 LcdShutdown (\r
   VOID\r
@@ -159,6 +172,11 @@ LcdShutdown (
   MmioWrite32 (HDLCD_REG_COMMAND, HDLCD_DISABLE);\r
 }\r
 \r
+/** Check for presence of HDLCD.\r
+\r
+  @retval EFI_SUCCESS            Returns success if platform implements a HDLCD\r
+                                 controller.\r
+**/\r
 EFI_STATUS\r
 LcdIdentify (\r
   VOID\r

diff --git a/ArmPlatformPkg/Library/LcdPlatformNullLib/LcdPlatformNullLib.c b/ArmPlatformPkg/Library/LcdPlatformNullLib/LcdPlatformNullLib.c
index b78d9a3bbd3e1fac4238f2be961a343020360a32..b76894c534fb413d87c77c528f0bb7d49862c78f 100644 (file)
--- a/ArmPlatformPkg/Library/LcdPlatformNullLib/LcdPlatformNullLib.c
+++ b/ArmPlatformPkg/Library/LcdPlatformNullLib/LcdPlatformNullLib.c
@@ -1,6 +1,7 @@
 /** @file\r
 \r
   Copyright (c) 2017, Linaro, Ltd. All rights reserved.\r
+  Copyright (c) 2018, Arm Limited. All rights reserved.\r
 \r
   This program and the accompanying materials\r
   are licensed and made available under the terms and conditions of the BSD License\r
@@ -17,6 +18,12 @@
 #include <Library/DebugLib.h>\r
 #include <Library/LcdPlatformLib.h>\r
 \r
+/** Platform related initialization function.\r
+\r
+  @param[in] Handle              Handle to the LCD device instance.\r
+\r
+  @retval EFI_UNSUPPORTED        Interface is not supported.\r
+**/\r
 EFI_STATUS\r
 LcdPlatformInitializeDisplay (\r
   IN EFI_HANDLE   Handle\r
@@ -26,6 +33,17 @@ LcdPlatformInitializeDisplay (
   return EFI_UNSUPPORTED;\r
 }\r
 \r
+/** Allocate VRAM memory in DRAM for the framebuffer\r
+  (unless it is reserved already).\r
+\r
+  The allocated address can be used to set the framebuffer.\r
+\r
+  @param[out] VramBaseAddress      A pointer to the framebuffer address.\r
+  @param[out] VramSize             A pointer to the size of the frame\r
+                                   buffer in bytes\r
+\r
+  @retval EFI_UNSUPPORTED          Interface is not supported.\r
+**/\r
 EFI_STATUS\r
 LcdPlatformGetVram (\r
   OUT EFI_PHYSICAL_ADDRESS*                 VramBaseAddress,\r
@@ -36,6 +54,14 @@ LcdPlatformGetVram (
   return EFI_UNSUPPORTED;\r
 }\r
 \r
+/** Return total number of modes supported.\r
+\r
+  Note: Valid mode numbers are 0 to MaxMode - 1\r
+  See Section 12.9 of the UEFI Specification 2.7\r
+\r
+  @retval UINT32             Zero number of modes supported\r
+                             in a NULL library implementation.\r
+**/\r
 UINT32\r
 LcdPlatformGetMaxMode (\r
   VOID\r
@@ -45,6 +71,12 @@ LcdPlatformGetMaxMode (
   return 0;\r
 }\r
 \r
+/** Set the requested display mode.\r
+\r
+  @param[in] ModeNumber            Mode Number.\r
+\r
+  @retval EFI_UNSUPPORTED          Interface is not supported.\r
+**/\r
 EFI_STATUS\r
 LcdPlatformSetMode (\r
   IN UINT32                                 ModeNumber\r
@@ -54,6 +86,15 @@ LcdPlatformSetMode (
   return EFI_UNSUPPORTED;\r
 }\r
 \r
+/** Return information for the requested mode number.\r
+\r
+  @param[in]  ModeNumber         Mode Number.\r
+  @param[out] Info               Pointer for returned mode information\r
+                                 (on success).\r
+\r
+  @retval EFI_UNSUPPORTED        Interface is not supported.\r
+\r
+**/\r
 EFI_STATUS\r
 LcdPlatformQueryMode (\r
   IN  UINT32                                ModeNumber,\r
@@ -64,6 +105,21 @@ LcdPlatformQueryMode (
   return EFI_UNSUPPORTED;\r
 }\r
 \r
+/** Return display timing information for the requested mode number.\r
+\r
+  @param[in]  ModeNumber          Mode Number.\r
+\r
+  @param[out] HRes                Pointer to horizontal resolution.\r
+  @param[out] HSync               Pointer to horizontal sync width.\r
+  @param[out] HBackPorch          Pointer to horizontal back porch.\r
+  @param[out] HFrontPorch         Pointer to horizontal front porch.\r
+  @param[out] VRes                Pointer to vertical resolution.\r
+  @param[out] VSync               Pointer to vertical sync width.\r
+  @param[out] VBackPorch          Pointer to vertical back porch.\r
+  @param[out] VFrontPorch         Pointer to vertical front porch.\r
+\r
+  @retval EFI_UNSUPPORTED         Interface is not supported.\r
+**/\r
 EFI_STATUS\r
 LcdPlatformGetTimings (\r
   IN  UINT32                              ModeNumber,\r
@@ -81,6 +137,15 @@ LcdPlatformGetTimings (
   return EFI_UNSUPPORTED;\r
 }\r
 \r
+/** Return bits per pixel information for a mode number.\r
+\r
+  @param[in]  ModeNumber          Mode Number.\r
+\r
+  @param[out] Bpp                 Pointer to value bits per pixel information.\r
+\r
+  @retval EFI_UNSUPPORTED         Interface is not supported.\r
+\r
+**/\r
 EFI_STATUS\r
 LcdPlatformGetBpp (\r
   IN  UINT32                                ModeNumber,\r

diff --git a/ArmPlatformPkg/Library/PL111Lcd/PL111Lcd.c b/ArmPlatformPkg/Library/PL111Lcd/PL111Lcd.c
index 3f3f7019f1d252995eab6d8c3d49db8be8e09e40..ccd7a4d1d43ad5c2f495683ac68236e17f3b55a5 100644 (file)
--- a/ArmPlatformPkg/Library/PL111Lcd/PL111Lcd.c
+++ b/ArmPlatformPkg/Library/PL111Lcd/PL111Lcd.c
@@ -1,4 +1,5 @@
 /** @file\r
+  This file contains the platform independent parts of PL111Lcd\r
 \r
   Copyright (c) 2011-2018, ARM Ltd. All rights reserved.<BR>\r
 \r
@@ -19,9 +20,12 @@
 \r
 #include "PL111Lcd.h"\r
 \r
-/** This file contains all the bits of the PL111 that are\r
-  platform independent.\r
+/** Check for presence of PL111.\r
 \r
+  @retval EFI_SUCCESS          Returns success if platform implements a\r
+                               PL111 controller.\r
+\r
+  @retval EFI_NOT_FOUND        PL111 display controller not found the plaform.\r
 **/\r
 EFI_STATUS\r
 LcdIdentify (\r
@@ -45,6 +49,12 @@ LcdIdentify (
   return EFI_NOT_FOUND;\r
 }\r
 \r
+/** Initialize display.\r
+\r
+  @param[in]  VramBaseAddress    Address of the framebuffer.\r
+\r
+  @retval EFI_SUCCESS            Initialization of display successful.\r
+**/\r
 EFI_STATUS\r
 LcdInitialize (\r
   IN EFI_PHYSICAL_ADDRESS   VramBaseAddress\r
@@ -60,6 +70,14 @@ LcdInitialize (
   return EFI_SUCCESS;\r
 }\r
 \r
+/** Set requested mode of the display.\r
+\r
+  @param[in] ModeNumbe           Display mode number.\r
+\r
+  @retval EFI_SUCCESS            Display mode set successfuly.\r
+  @retval EFI_DEVICE_ERROR       It returns an error if display timing\r
+                                 information is not available.\r
+**/\r
 EFI_STATUS\r
 LcdSetMode (\r
   IN UINT32  ModeNumber\r
@@ -130,6 +148,8 @@ LcdSetMode (
   return EFI_SUCCESS;\r
 }\r
 \r
+/** De-initializes the display.\r
+*/\r
 VOID\r
 LcdShutdown (\r
   VOID\r