1. Patchew
  2. EDK2
  3. [edk2-devel] [PATCH v2 0/7] N1Sdp ACPI table and configuration manager support
  4. View patch

[edk2-devel] [PATCH v2 1/7] Silicon/ARM/NeoverseN1Soc: Fix missing function documentation

Khasim Mohammed posted 7 patches 4 years, 4 months ago
There is a newer version of this series
[edk2-devel] [PATCH v2 1/7] Silicon/ARM/NeoverseN1Soc: Fix missing function documentation
Posted by Khasim Mohammed 4 years, 4 months ago 
This patch adds missing documentation for few of the functions
and fixes few formatting changes.

Signed-off-by: Khasim Syed Mohammed <khasim.mohammed@arm.com>
---
 .../PciHostBridgeLib/PciHostBridgeLib.c       | 18 ++++----
 .../Library/PlatformLib/PlatformLib.c         | 43 ++++++++++++++++---
 2 files changed, 47 insertions(+), 14 deletions(-)

diff --git a/Silicon/ARM/NeoverseN1Soc/Library/PciHostBridgeLib/PciHostBridgeLib.c b/Silicon/ARM/NeoverseN1Soc/Library/PciHostBridgeLib/PciHostBridgeLib.c
index 9332939f63..ac88415fd2 100644
--- a/Silicon/ARM/NeoverseN1Soc/Library/PciHostBridgeLib/PciHostBridgeLib.c
+++ b/Silicon/ARM/NeoverseN1Soc/Library/PciHostBridgeLib/PciHostBridgeLib.c
@@ -1,10 +1,10 @@
 /** @file
-*  PCI Host Bridge Library instance for ARM Neoverse N1 platform
-*
-*  Copyright (c) 2019 - 2020, ARM Limited. All rights reserved.
-*
-*  SPDX-License-Identifier: BSD-2-Clause-Patent
-*
+  PCI Host Bridge Library instance for ARM Neoverse N1 platform
+
+  Copyright (c) 2019 - 2021, ARM Limited. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
 **/
 
 #include <PiDxe.h>
@@ -96,7 +96,7 @@ STATIC PCI_ROOT_BRIDGE mPciRootBridge[] = {
 /**
   Return all the root bridge instances in an array.
 
-  @param Count  Return the count of root bridge instances.
+  @param Count            Return the count of root bridge instances.
 
   @return All the root bridge instances in an array.
           The array should be passed into PciHostBridgeFreeRootBridges()
@@ -115,8 +115,8 @@ PciHostBridgeGetRootBridges (
 /**
   Free the root bridge instances array returned from PciHostBridgeGetRootBridges().
 
-  @param Bridges The root bridge instances array.
-  @param Count   The count of the array.
+  @param Bridges          The root bridge instances array.
+  @param Count            The count of the array.
 **/
 VOID
 EFIAPI
diff --git a/Silicon/ARM/NeoverseN1Soc/Library/PlatformLib/PlatformLib.c b/Silicon/ARM/NeoverseN1Soc/Library/PlatformLib/PlatformLib.c
index f722080e56..d5ec0ff30d 100644
--- a/Silicon/ARM/NeoverseN1Soc/Library/PlatformLib/PlatformLib.c
+++ b/Silicon/ARM/NeoverseN1Soc/Library/PlatformLib/PlatformLib.c
@@ -1,9 +1,9 @@
 /** @file
-*
-*  Copyright (c) 2018-2020, ARM Limited. All rights reserved.
-*
-*  SPDX-License-Identifier: BSD-2-Clause-Patent
-*
+
+  Copyright (c) 2018-2021, ARM Limited. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
 **/
 
 #include <Library/ArmPlatformLib.h>
@@ -17,6 +17,12 @@ STATIC ARM_CORE_INFO mCoreInfoTable[] = {
   { 0x1, 0x1 }  // Cluster 1, Core 1
 };
 
+/**
+  Return the current Boot Mode.
+
+  This function returns the boot reason on the platform.
+
+**/
 EFI_BOOT_MODE
 ArmPlatformGetBootMode (
          VOID
@@ -25,6 +31,15 @@ ArmPlatformGetBootMode (
   return BOOT_WITH_FULL_CONFIGURATION;
 }
 
+/**
+  Initialize controllers that must be setup in the normal world.
+
+  This function is called by the ArmPlatformPkg/Pei or ArmPlatformPkg/Pei/PlatformPeim
+  in the PEI phase.
+
+  @param[in]    MpId          Processor ID
+
+**/
 RETURN_STATUS
 ArmPlatformInitialize (
   IN     UINTN                  MpId
@@ -33,6 +48,15 @@ ArmPlatformInitialize (
   return RETURN_SUCCESS;
 }
 
+/**
+  Populate the Platform core information.
+
+  This function populates the ARM_MP_CORE_INFO_PPI with information about the cores.
+
+  @param[out]   CoreCount     Number of cores
+  @param[out]   ArmCoreTable  Table containing information about the cores
+
+**/
 EFI_STATUS
 PrePeiCoreGetMpCoreInfo (
      OUT UINTN                  *CoreCount,
@@ -56,6 +80,15 @@ EFI_PEI_PPI_DESCRIPTOR gPlatformPpiTable[] = {
   }
 };
 
+/**
+  Return the Platform specific PPIs
+
+  This function exposes the N1Sdp Specific PPIs.
+
+  @param[out]   PpiListSize   Size in Bytes of the Platform PPI List
+  @param[out]   PpiList       Platform PPI List
+
+**/
 VOID
 ArmPlatformGetPlatformPpiList (
      OUT UINTN                  *PpiListSize,
-- 
2.17.1



-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#81733): https://edk2.groups.io/g/devel/message/81733
Mute This Topic: https://groups.io/mt/86220127/1787277
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org]
-=-=-=-=-=-=-=-=-=-=-=-
Re: [edk2-devel] [PATCH v2 1/7] Silicon/ARM/NeoverseN1Soc: Fix missing function documentation
Posted by PierreGondois 4 years, 4 months ago 
Hi Khasim,

I had some questions about this path:

On 10/10/21 19:29, Khasim Mohammed via groups.io wrote:
> This patch adds missing documentation for few of the functions
> and fixes few formatting changes.
>
> Signed-off-by: Khasim Syed Mohammed <khasim.mohammed@arm.com>
> ---
>  .../PciHostBridgeLib/PciHostBridgeLib.c       | 18 ++++----
>  .../Library/PlatformLib/PlatformLib.c         | 43 ++++++++++++++++---
>  2 files changed, 47 insertions(+), 14 deletions(-)
>
> diff --git a/Silicon/ARM/NeoverseN1Soc/Library/PciHostBridgeLib/PciHostBridgeLib.c b/Silicon/ARM/NeoverseN1Soc/Library/PciHostBridgeLib/PciHostBridgeLib.c
> index 9332939f63..ac88415fd2 100644
> --- a/Silicon/ARM/NeoverseN1Soc/Library/PciHostBridgeLib/PciHostBridgeLib.c
> +++ b/Silicon/ARM/NeoverseN1Soc/Library/PciHostBridgeLib/PciHostBridgeLib.c

Are the modifications in this file required ? The indentation seems
correct to me

> @@ -1,10 +1,10 @@
>  /** @file
> -*  PCI Host Bridge Library instance for ARM Neoverse N1 platform
> -*
> -*  Copyright (c) 2019 - 2020, ARM Limited. All rights reserved.
> -*
> -*  SPDX-License-Identifier: BSD-2-Clause-Patent
> -*
> +  PCI Host Bridge Library instance for ARM Neoverse N1 platform
> +
> +  Copyright (c) 2019 - 2021, ARM Limited. All rights reserved.<BR>
> +
> +  SPDX-License-Identifier: BSD-2-Clause-Patent
> +
>  **/
>  
>  #include <PiDxe.h>
> @@ -96,7 +96,7 @@ STATIC PCI_ROOT_BRIDGE mPciRootBridge[] = {
>  /**
>    Return all the root bridge instances in an array.
>  
> -  @param Count  Return the count of root bridge instances.
> +  @param Count            Return the count of root bridge instances.
>  
>    @return All the root bridge instances in an array.
>            The array should be passed into PciHostBridgeFreeRootBridges()
> @@ -115,8 +115,8 @@ PciHostBridgeGetRootBridges (
>  /**
>    Free the root bridge instances array returned from PciHostBridgeGetRootBridges().
>  
> -  @param Bridges The root bridge instances array.
> -  @param Count   The count of the array.
> +  @param Bridges          The root bridge instances array.
> +  @param Count            The count of the array.
>  **/
>  VOID
>  EFIAPI
> diff --git a/Silicon/ARM/NeoverseN1Soc/Library/PlatformLib/PlatformLib.c b/Silicon/ARM/NeoverseN1Soc/Library/PlatformLib/PlatformLib.c
> index f722080e56..d5ec0ff30d 100644
> --- a/Silicon/ARM/NeoverseN1Soc/Library/PlatformLib/PlatformLib.c
> +++ b/Silicon/ARM/NeoverseN1Soc/Library/PlatformLib/PlatformLib.c
> @@ -1,9 +1,9 @@
>  /** @file
> -*
> -*  Copyright (c) 2018-2020, ARM Limited. All rights reserved.
> -*
> -*  SPDX-License-Identifier: BSD-2-Clause-Patent
> -*
> +
> +  Copyright (c) 2018-2021, ARM Limited. All rights reserved.<BR>
> +
> +  SPDX-License-Identifier: BSD-2-Clause-Patent
> +
>  **/
>  
>  #include <Library/ArmPlatformLib.h>
> @@ -17,6 +17,12 @@ STATIC ARM_CORE_INFO mCoreInfoTable[] = {
>    { 0x1, 0x1 }  // Cluster 1, Core 1
>  };
>  
> +/**
> +  Return the current Boot Mode.
> +
> +  This function returns the boot reason on the platform.

There are the '@return' and '@retval' keywords to indicate what a
function returns.

I think here it should be:
@return The boot reason on the platform.

> +
> +**/
>  EFI_BOOT_MODE
>  ArmPlatformGetBootMode (
>           VOID
> @@ -25,6 +31,15 @@ ArmPlatformGetBootMode (
>    return BOOT_WITH_FULL_CONFIGURATION;
>  }
>  
> +/**
> +  Initialize controllers that must be setup in the normal world.
> +
> +  This function is called by the ArmPlatformPkg/Pei or ArmPlatformPkg/Pei/PlatformPeim
> +  in the PEI phase.
It seems to exceed the 80 chars.
> +
> +  @param[in]    MpId          Processor ID
Same here, can you add:
@retval RETURN_SUCCESS
> +
> +**/
>  RETURN_STATUS
>  ArmPlatformInitialize (
>    IN     UINTN                  MpId
> @@ -33,6 +48,15 @@ ArmPlatformInitialize (
>    return RETURN_SUCCESS;
>  }
>  
> +/**
> +  Populate the Platform core information.
> +
> +  This function populates the ARM_MP_CORE_INFO_PPI with information about the cores.
It seems to exceed the 80 chars.
> +
> +  @param[out]   CoreCount     Number of cores
> +  @param[out]   ArmCoreTable  Table containing information about the cores
> +
Same here, can you add:
@retval RETURN_SUCCESS
> +**/
>  EFI_STATUS
>  PrePeiCoreGetMpCoreInfo (
>       OUT UINTN                  *CoreCount,
> @@ -56,6 +80,15 @@ EFI_PEI_PPI_DESCRIPTOR gPlatformPpiTable[] = {
>    }
>  };
>  
> +/**
> +  Return the Platform specific PPIs
> +
> +  This function exposes the N1Sdp Specific PPIs.
> +
> +  @param[out]   PpiListSize   Size in Bytes of the Platform PPI List
> +  @param[out]   PpiList       Platform PPI List
> +
> +**/
>  VOID
>  ArmPlatformGetPlatformPpiList (
>       OUT UINTN                  *PpiListSize,


-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#81876): https://edk2.groups.io/g/devel/message/81876
Mute This Topic: https://groups.io/mt/86220127/1787277
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org]
-=-=-=-=-=-=-=-=-=-=-=-

Patchew 2.1-devel-b67e4c2

© 2016 - 2026 Red Hat, Inc.