ArmPlatformPkg: Tidy Lcd code: Updated comments
authorGirish Pathak <girish.pathak at arm.com>
Tue, 26 Sep 2017 20:15:12 +0000 (21:15 +0100)
committerLeif Lindholm <leif.lindholm@linaro.org>
Mon, 23 Apr 2018 11:00:23 +0000 (12:00 +0100)
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>
ArmPlatformPkg/Drivers/LcdGraphicsOutputDxe/LcdGraphicsOutputDxe.c
ArmPlatformPkg/Include/Library/LcdPlatformLib.h
ArmPlatformPkg/Library/HdLcd/HdLcd.c
ArmPlatformPkg/Library/LcdPlatformNullLib/LcdPlatformNullLib.c
ArmPlatformPkg/Library/PL111Lcd/PL111Lcd.c

index 905eb26..872361c 100644 (file)
@@ -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
 \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
index 3d13e41..e51e786 100644 (file)
@@ -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
 #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
 #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
 #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
 #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
index 2cd1be9..be4ccfd 100644 (file)
@@ -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
 \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
index b78d9a3..b76894c 100644 (file)
@@ -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
 #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
index 3f3f701..ccd7a4d 100644 (file)
@@ -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
 \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