src/vendorcode/amd/agesa/f15/Proc/Common/CommonPage.h

   1 /* $NoKeywords:$ */
   2 /**
   3  * @file
   4  *
   5  * Create outline and references for Processor Common Component mainpage documentation.
   6  *
   7  * Design guides, maintenance guides, and general documentation, are
   8  * collected using this file onto the documentation mainpage.
   9  * This file contains doxygen comment blocks, only.
  10  *
  11  * @xrefitem bom "File Content Label" "Release Content"
  12  * @e project:      AGESA
  13  * @e sub-project:  Documentation
  14  * @e \$Revision: 44324 $   @e \$Date: 2010-12-22 02:16:51 -0700 (Wed, 22 Dec 2010) $
  15  *
  16  */
  17 /*
  18  ******************************************************************************
  19  *
  20  * Copyright (C) 2012 Advanced Micro Devices, Inc.
  21  * All rights reserved.
  22  *
  23  * Redistribution and use in source and binary forms, with or without
  24  * modification, are permitted provided that the following conditions are met:
  25  *     * Redistributions of source code must retain the above copyright
  26  *       notice, this list of conditions and the following disclaimer.
  27  *     * Redistributions in binary form must reproduce the above copyright
  28  *       notice, this list of conditions and the following disclaimer in the
  29  *       documentation and/or other materials provided with the distribution.
  30  *     * Neither the name of Advanced Micro Devices, Inc. nor the names of
  31  *       its contributors may be used to endorse or promote products derived
  32  *       from this software without specific prior written permission.
  33  *
  34  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  35  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  36  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  37  * DISCLAIMED. IN NO EVENT SHALL ADVANCED MICRO DEVICES, INC. BE LIABLE FOR ANY
  38  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  39  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  40  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  41  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  42  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  43  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  44  *
  45  ******************************************************************************
  46  */
  47
  48 /**
  49  * @page commonmain Processor Common Component Documentation
  50  *
  51  * Additional documentation for the Common component consists of
  52  *
  53  * - Maintenance Guides:
  54  *   - @subpage amdconfigparamname "Naming Guidelines for type AMD_CONFIG_PARAMS"
  55  * - Design Guides:
  56  *   - add here >>>
  57  *
  58  */
  59
  60 /**
  61  * @page amdconfigparamname Naming Guidelines for type AMD_CONFIG_PARAMS
  62  * @par
  63  * These are the guidelines for naming objects of type AMD_CONFIG_PARAMS and AMD_CONFIG_PARAMS * in AGESA code.
  64  * <ul>
  65  *
  66  * <li>
  67  * Formal parameter names of type AMD_CONFIG_PARAMS and AMD_CONFIG_PARAMS * will always be named
  68  * StdHeader. This covers all function prototypes, function definitions, and method typedefs (a
  69  * typedef of a function prototype) in AGESA code. Examples:
  70  * @n @code
  71  * VOID
  72  *   LibAmdPciFindNextCap (
  73  *     IN OUT   PCI_ADDR *Address,
  74  *     IN       AMD_CONFIG_PARAMS *StdHeader
  75  *     )
  76  *
  77  * typedef VOID F_DO_TABLE_ENTRY (
  78  *   IN       TABLE_ENTRY_DATA       *CurrentEntry,
  79  *   IN       PLATFORM_CONFIGURATION *PlatformConfig,
  80  *   IN       AMD_CONFIG_PARAMS      *StdHeader
  81  *   );
  82  *
  83  * @endcode
  84  *
  85  * <li>
  86  * Structure members of type AMD_CONFIG_PARAMS or AMD_CONFIG_PARAMS * will always be named StdHeader. Examples:
  87  * @n @code
  88    /// Example of struct member naming.
  89  * typedef struct {
  90  *   IN OUT   AMD_CONFIG_PARAMS StdHeader;             ///< Standard Header
  91  *   IN       PLATFORM_CONFIGURATION PlatformConfig;   ///< platform operational characteristics.
  92  * } AMD_CPU_RECOVERY_PARAMS;
  93  *
  94  * @endcode
  95  *
  96  * <li>
  97  * Routines which define local variables of type AMD_CONFIG_PARAMS or AMD_CONFIG_PARAMS * should
  98  * name the local variable as closely as practical to StdHeader, but otherwise freedom is allowed. Example:
  99  * @n @code
 100  * AMD_CONFIG_PARAMS *NewStdHeader;
 101  * [...]
 102  * NewStdHeader = (AMD_CONFIG_PARAMS *)AllocHeapParams.BufferPtr;
 103  * @endcode
 104  *
 105  * <li>
 106  * Arguments to routines with AMD_CONFIG_PARAMS or AMD_CONFIG_PARAMS * formal parameters are not
 107  * checked.  Freedom is allowed in order to conform to these guidelines in a practical, readable
 108  * way.  This includes typecast arguments.  Examples:
 109  * @n @code
 110  * Status = GetEventLog (&LogEvent, (AMD_CONFIG_PARAMS *)Event);
 111  *
 112  * MemS3ExitSelfRefRegDA (NBPtr, &MemPtr->StdHeader);
 113  * @endcode
 114  *
 115  * </ul>
 116  *
 117  */