[PATCH v2 02/13] ArmPlatformPkg: Tidy Lcd code: Updated comments

[evan.lloyd@arm.com]

From: Girish Pathak <girish.pathak at arm.com>

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>
---
 ArmPlatformPkg/Include/Library/LcdPlatformLib.h                    | 92 +++++++++++++++-----
 ArmPlatformPkg/Drivers/LcdGraphicsOutputDxe/LcdGraphicsOutputDxe.c | 20 ++---
 ArmPlatformPkg/Library/HdLcd/HdLcd.c                               | 29 +++++-
 ArmPlatformPkg/Library/PL111Lcd/PL111Lcd.c                         | 24 ++++-
 4 files changed, 127 insertions(+), 38 deletions(-)

diff --git a/ArmPlatformPkg/Include/Library/LcdPlatformLib.h b/ArmPlatformPkg/Include/Library/LcdPlatformLib.h
index b9316ec8de8425a83e2f627f5c24821ff9a2f750..2a70307031fc21c8fb0d655d358ca9a102a95920 100644
--- a/ArmPlatformPkg/Include/Library/LcdPlatformLib.h
+++ b/ArmPlatformPkg/Include/Library/LcdPlatformLib.h
@@ -18,9 +18,7 @@
 
 #define LCD_VRAM_SIZE                     SIZE_8MB
 
-//
 // Modes definitions
-//
 #define VGA                               0
 #define SVGA                              1
 #define XGA                               2
@@ -29,9 +27,7 @@
 #define UXGA                              5
 #define HD                                6
 
-//
 // VGA Mode: 640 x 480
-//
 #define VGA_H_RES_PIXELS                  640
 #define VGA_V_RES_PIXELS                  480
 #define VGA_OSC_FREQUENCY                 23750000  /* 0x016A6570 */
@@ -44,9 +40,7 @@
 #define VGA_V_FRONT_PORCH                 (  3 - 1)
 #define VGA_V_BACK_PORCH                  ( 13 - 1)
 
-//
 // SVGA Mode: 800 x 600
-//
 #define SVGA_H_RES_PIXELS                 800
 #define SVGA_V_RES_PIXELS                 600
 #define SVGA_OSC_FREQUENCY                38250000  /* 0x0247A610 */
@@ -59,9 +53,7 @@
 #define SVGA_V_FRONT_PORCH                (  3 - 1)
 #define SVGA_V_BACK_PORCH                 ( 17 - 1)
 
-//
 // XGA Mode: 1024 x 768
-//
 #define XGA_H_RES_PIXELS                  1024
 #define XGA_V_RES_PIXELS                  768
 #define XGA_OSC_FREQUENCY                 63500000  /* 0x03C8EEE0 */
@@ -74,9 +66,7 @@
 #define XGA_V_FRONT_PORCH                 (  3 - 1)
 #define XGA_V_BACK_PORCH                  ( 23 - 1)
 
-//
 // SXGA Mode: 1280 x 1024
-//
 #define SXGA_H_RES_PIXELS                 1280
 #define SXGA_V_RES_PIXELS                 1024
 #define SXGA_OSC_FREQUENCY                109000000  /* 0x067F3540 */
@@ -89,9 +79,7 @@
 #define SXGA_V_FRONT_PORCH                (  3 - 1)
 #define SXGA_V_BACK_PORCH                 ( 29 - 1)
 
-//
 // WSXGA+ Mode: 1680 x 1050
-//
 #define WSXGA_H_RES_PIXELS                1680
 #define WSXGA_V_RES_PIXELS                1050
 #define WSXGA_OSC_FREQUENCY               147000000  /* 0x08C30AC0 */
@@ -104,9 +92,7 @@
 #define WSXGA_V_FRONT_PORCH               (  4 - 1)
 #define WSXGA_V_BACK_PORCH                ( 41 - 1)
 
-//
 // UXGA Mode: 1600 x 1200
-//
 #define UXGA_H_RES_PIXELS                 1600
 #define UXGA_V_RES_PIXELS                 1200
 #define UXGA_OSC_FREQUENCY                161000000  /* 0x0998AA40 */
@@ -119,9 +105,7 @@
 #define UXGA_V_FRONT_PORCH                (  3 - 1)
 #define UXGA_V_BACK_PORCH                 ( 38 - 1)
 
-//
 // HD Mode: 1920 x 1080
-//
 #define HD_H_RES_PIXELS                   1920
 #define HD_V_RES_PIXELS                   1080
 #define HD_OSC_FREQUENCY                  165000000  /* 0x09D5B340 */
@@ -134,10 +118,7 @@
 #define HD_V_FRONT_PORCH                  (  3 - 1)
 #define HD_V_BACK_PORCH                   ( 32 - 1)
 
-//
 // Colour Masks
-//
-
 #define LCD_24BPP_RED_MASK              0x00FF0000
 #define LCD_24BPP_GREEN_MASK            0x0000FF00
 #define LCD_24BPP_BLUE_MASK             0x000000FF
@@ -158,7 +139,7 @@
 #define LCD_12BPP_444_BLUE_MASK         0x0000000F
 #define LCD_12BPP_444_RESERVED_MASK     0x0000F000
 
-/** The enumeration indexes maps the PL111 LcdBpp values used in the LCD Control
+/** The enumeration maps the PL111 LcdBpp values used in the LCD Control
   Register
 **/
 typedef enum {
@@ -172,33 +153,94 @@ typedef enum {
   LCD_BITS_PER_PIXEL_12_444
 } LCD_BPP;
 
+/** Platform related initialization function.
+
+  @param[in] Handle              Handle to the LCD device instance.
+
+  @retval EFI_SUCCESS            Plaform library initialized successfully.
+  @retval !(EFI_SUCCESS)         Other errors.
+**/
 EFI_STATUS
 LcdPlatformInitializeDisplay (
   IN EFI_HANDLE   Handle
   );
 
+/** Allocate VRAM memory in DRAM for the frame buffer
+  (unless it is reserved already).
+
+  The allocated address can be used to set the frame buffer.
+
+  @param[out] VramBaseAddress      A pointer to the frame buffer address.
+  @param[out] VramSize             A pointer to the size of the frame
+                                   buffer in bytes
+
+  @retval EFI_SUCCESS              Frame buffer memory allocated successfully.
+  @retval !(EFI_SUCCESS)           Other errors.
+**/
 EFI_STATUS
 LcdPlatformGetVram (
   OUT EFI_PHYSICAL_ADDRESS*                 VramBaseAddress,
   OUT UINTN*                                VramSize
   );
 
+/** Return total number of modes supported.
+
+  Note: Valid mode numbers are 0 to MaxMode - 1
+  See Section 12.9 of the UEFI Specification 2.7
+
+  @retval UINT32             Mode Number.
+**/
 UINT32
 LcdPlatformGetMaxMode (
   VOID
   );
 
+/** Set the requested display mode.
+
+  @param[in] ModeNumber            Mode Number.
+
+  @retval  EFI_SUCCESS             Mode set successfully.
+  @retval  EFI_INVALID_PARAMETER   Requested mode not found.
+  @retval  !(EFI_SUCCESS)          Other errors.
+**/
 EFI_STATUS
 LcdPlatformSetMode (
   IN UINT32                                 ModeNumber
   );
 
+/** Return information for the requested mode number.
+
+  @param[in]  ModeNumber         Mode Number.
+  @param[out] Info               Pointer for returned mode information
+                                 (on success).
+
+  @retval EFI_SUCCESS             Mode information for the requested mode
+                                  returned successfully.
+  @retval EFI_INVALID_PARAMETER   Requested mode not found.
+**/
 EFI_STATUS
 LcdPlatformQueryMode (
   IN  UINT32                                ModeNumber,
   OUT EFI_GRAPHICS_OUTPUT_MODE_INFORMATION  *Info
   );
 
+/** Return display timing information for the requested mode number.
+
+  @param[in]  ModeNumber          Mode Number.
+
+  @param[out] HRes                Pointer to horizontal resolution.
+  @param[out] HSync               Pointer to horizontal sync width.
+  @param[out] HBackPorch          Pointer to horizontal back porch.
+  @param[out] HFrontPorch         Pointer to horizontal front porch.
+  @param[out] VRes                Pointer to vertical resolution.
+  @param[out] VSync               Pointer to vertical sync width.
+  @param[out] VBackPorch          Pointer to vertical back porch.
+  @param[out] VFrontPorch         Pointer to vertical front porch.
+
+  @retval EFI_SUCCESS             Display timing information for the requested
+                                  mode returned successfully.
+  @retval EFI_INVALID_PARAMETER   Requested mode not found.
+**/
 EFI_STATUS
 LcdPlatformGetTimings (
   IN  UINT32                              ModeNumber,
@@ -212,6 +254,16 @@ LcdPlatformGetTimings (
   OUT UINT32*                             VFrontPorch
   );
 
+/** Return bits per pixel information for a mode number.
+
+  @param[in]  ModeNumber          Mode Number.
+
+  @param[out] Bpp                 Pointer to value bits per pixel.
+
+  @retval EFI_SUCCESS             Bit per pixel information for the requested
+                                  mode returned successfully.
+  @retval EFI_INVALID_PARAMETER   Requested mode not found.
+**/
 EFI_STATUS
 LcdPlatformGetBpp (
   IN  UINT32                                ModeNumber,
diff --git a/ArmPlatformPkg/Drivers/LcdGraphicsOutputDxe/LcdGraphicsOutputDxe.c b/ArmPlatformPkg/Drivers/LcdGraphicsOutputDxe/LcdGraphicsOutputDxe.c
index 948e5692c943cdf62a10f4e6290470d3ccd334f1..72895a751784413d50e2cbf4550091b896a4f1d3 100644
--- a/ArmPlatformPkg/Drivers/LcdGraphicsOutputDxe/LcdGraphicsOutputDxe.c
+++ b/ArmPlatformPkg/Drivers/LcdGraphicsOutputDxe/LcdGraphicsOutputDxe.c
@@ -1,13 +1,14 @@
 /** @file
+  This file implements the Graphics Output protocol for Arm platforms
 
- Copyright (c) 2011-2017, ARM Ltd. All rights reserved.<BR>
- This program and the accompanying materials
- are licensed and made available under the terms and conditions of the BSD License
- which accompanies this distribution.  The full text of the license may be found at
- http://opensource.org/licenses/bsd-license.php
+  Copyright (c) 2011-2017, ARM Ltd. All rights reserved.<BR>
+  This program and the accompanying materials
+  are licensed and made available under the terms and conditions of the BSD License
+  which accompanies this distribution.  The full text of the license may be found at
+  http://opensource.org/licenses/bsd-license.php
 
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
 **/
 
@@ -22,11 +23,6 @@
 
 #include "LcdGraphicsOutputDxe.h"
 
-/** This file implements the Graphics Output protocol on ArmVersatileExpress
-  using the Lcd controller
-
-**/
-
 //
 // Global variables
 //
diff --git a/ArmPlatformPkg/Library/HdLcd/HdLcd.c b/ArmPlatformPkg/Library/HdLcd/HdLcd.c
index f1fffb1e83173f03f044fc0f4a5ad5c0b864695b..079fe64ccf30dc21c357298511aeb660faa67e4a 100644
--- a/ArmPlatformPkg/Library/HdLcd/HdLcd.c
+++ b/ArmPlatformPkg/Library/HdLcd/HdLcd.c
@@ -1,4 +1,5 @@
 /** @file
+  This file contains the platform independent parts of HdLcd
 
   Copyright (c) 2011-2017, ARM Ltd. All rights reserved.<BR>
 
@@ -21,10 +22,6 @@
 
 #include "HdLcd.h"
 
-/** This file contains all the bits of the Lcd that are
-  platform independent.
-**/
-
 STATIC
 UINTN
 GetBytesPerPixel (
@@ -51,6 +48,12 @@ GetBytesPerPixel (
   }
 }
 
+/** Initialize display.
+
+  @param[in]  VramBaseAddress    Address of the frame buffer.
+
+  @retval EFI_SUCCESS            Display initialization successful.
+**/
 EFI_STATUS
 LcdInitialize (
   IN EFI_PHYSICAL_ADDRESS   VramBaseAddress
@@ -82,6 +85,14 @@ LcdInitialize (
   return EFI_SUCCESS;
 }
 
+/** Set requested mode of the display.
+
+  @param[in] ModeNumber          Display mode number.
+
+  @retval EFI_SUCCESS            Display mode set successfully.
+  @retval EFI_DEVICE_ERROR       Reurns an error if display timing
+                                 information is not available.
+**/
 EFI_STATUS
 LcdSetMode (
   IN UINT32  ModeNumber
@@ -150,6 +161,8 @@ LcdSetMode (
   return EFI_SUCCESS;
 }
 
+/** De-initializes the display.
+**/
 VOID
 LcdShutdown (VOID)
 {
@@ -157,6 +170,14 @@ LcdShutdown (VOID)
   MmioWrite32 (HDLCD_REG_COMMAND, HDLCD_DISABLE);
 }
 
+/** Check for presence of HDLCD.
+
+  @retval EFI_SUCCESS            Returns success if platform implements a HDLCD
+                                 controller.
+
+  @retval EFI_NOT_FOUND          HDLCD display controller not found on the
+                                 platform
+**/
 EFI_STATUS
 LcdIdentify (VOID)
 {
diff --git a/ArmPlatformPkg/Library/PL111Lcd/PL111Lcd.c b/ArmPlatformPkg/Library/PL111Lcd/PL111Lcd.c
index 19a5f3c58c63173f6528d7c1eedf51053dbeaf7e..b1b7d0dd19076e3afba0d144af8d95b9f350006c 100644
--- a/ArmPlatformPkg/Library/PL111Lcd/PL111Lcd.c
+++ b/ArmPlatformPkg/Library/PL111Lcd/PL111Lcd.c
@@ -1,4 +1,5 @@
 /** @file
+  This file contains the platform independent parts of PL111Lcd
 
   Copyright (c) 2011-2017, ARM Ltd. All rights reserved.<BR>
 
@@ -19,9 +20,12 @@
 
 #include "PL111Lcd.h"
 
-/** This file contains all the bits of the PL111 that are
-  platform independent.
+/** Check for presence of PL111.
 
+  @retval EFI_SUCCESS          Returns success if platform implements a
+                               PL111 controller.
+
+  @retval EFI_NOT_FOUND        PL111 display controller not found the plaform.
 **/
 EFI_STATUS
 LcdIdentify (VOID)
@@ -43,6 +47,12 @@ LcdIdentify (VOID)
   return EFI_NOT_FOUND;
 }
 
+/** Initialize display.
+
+  @param[in]  VramBaseAddress    Address of the frame buffer.
+
+  @retval EFI_SUCCESS            Initialization of display successful.
+**/
 EFI_STATUS
 LcdInitialize (
   IN EFI_PHYSICAL_ADDRESS   VramBaseAddress
@@ -58,6 +68,14 @@ LcdInitialize (
   return EFI_SUCCESS;
 }
 
+/** Set requested mode of the display.
+
+  @param[in] ModeNumbe           Display mode number.
+
+  @retval EFI_SUCCESS            Display set mode successfuly.
+  @retval EFI_DEVICE_ERROR       It returns an error if display timing
+                                 information is not available.
+**/
 EFI_STATUS
 LcdSetMode (
   IN UINT32  ModeNumber
@@ -128,6 +146,8 @@ LcdSetMode (
   return EFI_SUCCESS;
 }
 
+/** De-initializes the display.
+*/
 VOID
 LcdShutdown (VOID)
 {
-- 
Guid("CE165669-3EF3-493F-B85D-6190EE5B9759")