src/vendorcode/amd/agesa/f15/Include/OptionsPage.h

   1 /* $NoKeywords:$ */
   2 /**
   3  * @file
   4  *
   5  * Create outline and references for Build Configuration and Options 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: 52274 $   @e \$Date: 2011-05-04 01:00:15 -0600 (Wed, 04 May 2011) $
  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 optionmain Build Configuration and Options Documentation
  50  *
  51  * Additional documentation for the Build Configuration and Options component consists of
  52  *
  53  * - Introduction and Overview to Build Options
  54  *   - @subpage platforminstall "Platform Build Options"
  55  *   - @subpage bldcfg "Build Configuration Item Cross Reference"
  56  *   - @subpage examplecustomizations "Customization Examples"
  57  * - Maintenance Guides:
  58  *   -  For debug of the Options system, use compiler options
  59  *      @n <tt>      /P /EP /C /FAs      </tt> @n
  60  *      PreProcessor output is produced in an .i file in the directory where the project
  61  *      file is located.
  62  * - Design Guides:
  63  *   - add here >>>
  64  *
  65  */
  66
  67 /**
  68  * @page platforminstall Platform Build Options.
  69  *
  70  * Build options are boolean constants. The purpose of build options is to remove code
  71  * from the build to reduce the overall code size present in the ROM image. Unless
  72  * otherwise specified, the default action is to include all options. If a build option is
  73  * not specifically listed as disabled, then it is included into the build.
  74  *
  75  * The documented build options are imported from a user controlled file for
  76  * processing. The build options for all platform solutions are listed below:
  77  *
  78  * @anchor BLDOPT_REMOVE_UDIMMS_SUPPORT
  79  * @li @e BLDOPT_REMOVE_UDIMMS_SUPPORT @n
  80  *        If unbuffered DIMMs are NOT expected to be required in the system, the code that
  81  *        handles unbuffered DIMMs can be removed from the build.
  82  *
  83  * @anchor BLDOPT_REMOVE_RDIMMS_SUPPORT
  84  * @li @e  BLDOPT_REMOVE_RDIMMS_SUPPORT @n
  85  *         If registered DIMMs are NOT expected to be required in the system, the code
  86  *         that handles registered DIMMs can be removed from the build.
  87  *
  88   * @anchor BLDOPT_REMOVE_LRDIMMS_SUPPORT
  89  * @li @e  BLDOPT_REMOVE_LRDIMMS_SUPPORT @n
  90  *         If Load Reduced DIMMs are NOT expected to be required in the system, the code
  91  *         that handles Load Reduced DIMMs can be removed from the build.
  92  *
  93  *     @note The above three options operate independently from each other; however, at
  94  *     least one of the unbuffered , registered or load reduced DIMM options must be present in the build.
  95  *
  96  * @anchor BLDOPT_REMOVE_ECC_SUPPORT
  97  * @li @e  BLDOPT_REMOVE_ECC_SUPPORT @n
  98  *         Use this option to remove the code for Error Checking & Correction.
  99  *
 100  * @anchor BLDOPT_REMOVE_BANK_INTERLEAVE
 101  * @li @e  BLDOPT_REMOVE_BANK_INTERLEAVE @n
 102  *         Interleaving is a mechanism to do performance fine tuning. This option
 103  *         interleaves memory between banks on a DIMM.
 104  *
 105  * @anchor BLDOPT_REMOVE_DCT_INTERLEAVE
 106  * @li @e  BLDOPT_REMOVE_DCT_INTERLEAVE @n
 107  *         Interleaving is a mechanism to do performance fine tuning. This option
 108  *         interleaves memory from two DRAM controllers.
 109  *
 110  * @anchor BLDOPT_REMOVE_NODE_INTERLEAVE
 111  * @li @e  BLDOPT_REMOVE_NODE_INTERLEAVE @n
 112  *         Interleaving is a mechanism to do performance fine tuning. This option
 113  *         interleaves memory from two HyperTransport nodes.
 114  *
 115  * @anchor BLDOPT_REMOVE_PARALLEL_TRAINING
 116  * @li @e  BLDOPT_REMOVE_PARALLEL_TRAINING @n
 117  *         For multi-socket systems, training memory in parallel can reduce the time
 118  *         needed to boot.
 119  *
 120  * @anchor BLDOPT_REMOVE_ONLINE_SPARE_SUPPORT
 121  * @li @e  BLDOPT_REMOVE_ONLINE_SPARE_SUPPORT @n
 122  *         Online Spare support is removed by this option.
 123  *
 124  * @anchor BLDOPT_REMOVE_MULTISOCKET_SUPPORT
 125  * @li @e BLDOPT_REMOVE_MULTISOCKET_SUPPORT @n
 126  *        Many systems use only a single socket and may benefit in code space to remove
 127  *        this code. However, certain processors have multiple HyperTransport nodes
 128  *        within a single socket. For these processors, the multi-node support is
 129  *        required and this option has no effect.
 130  *
 131  * @anchor BLDOPT_REMOVE_ACPI_PSTATES
 132  * @li @e  BLDOPT_REMOVE_ACPI_PSTATES @n
 133  *         This option removes the code that generates the ACPI tables used in power
 134  *         management.
 135  *
 136  * @anchor BLDCFG_PSTATE_HPC_MODE
 137  * @li @e  BLDCFG_PSTATE_HPC_MODE @n
 138  *         This option enables PStates high performance computing mode (HPC mode)
 139  *
 140  * @anchor BLDOPT_REMOVE_SRAT
 141  * @li @e  BLDOPT_REMOVE_SRAT @n
 142  *         This option removes the code that generates the SRAT tables used in performance
 143  *         tuning.
 144  *
 145  * @anchor BLDOPT_REMOVE_SLIT
 146  * @li @e  BLDOPT_REMOVE_SLIT @n
 147  *         This option removes the code that generates the SLIT tables used in performance
 148  *         tuning.
 149  *
 150  * @anchor BLDOPT_REMOVE_WHEA
 151  * @li @e  BLDOPT_REMOVE_WHEA @n
 152  *         This option removes the code that generates the WHEA tables used in error
 153  *         handling and reporting.
 154  *
 155  * @anchor BLDOPT_REMOVE_DMI
 156  * @li @e  BLDOPT_REMOVE_DMI @n
 157  *         This option removes the code that generates the DMI tables used in system
 158  *         management.
 159  *
 160  * @anchor BLDOPT_REMOVE_DQS_TRAINING
 161  * @li @e  BLDOPT_REMOVE_DQS_TRAINING @n
 162  *         This option removes the code used in memory performance tuning.
 163  *
 164  * @anchor BLDOPT_REMOVE_EARLY_SAMPLES
 165  * @li @e  BLDOPT_REMOVE_EARLY_SAMPLES @n
 166  *         Special support for Early Samples is included. Default setting is FALSE.
 167  *
 168  * @anchor BLDOPT_REMOVE_HT_ASSIST
 169  * @li @e  BLDOPT_REMOVE_HT_ASSIST @n
 170  *         This option removes the code which implements the HT Assist feature.
 171  *
 172  * @anchor BLDOPT_REMOVE_ATM_MODE
 173  * @li @e  BLDOPT_REMOVE_ATM_MODE @n
 174  *         This option removes the code which implements the ATM feature.
 175  *
 176  * @anchor BLDOPT_REMOVE_MSG_BASED_C1E
 177  * @li @e  BLDOPT_REMOVE_MSG_BASED_C1E @n
 178  *         This option removes the code which implements the Message Based C1e feature.
 179  *
 180  * @anchor BLDOPT_REMOVE_C6_STATE
 181  * @li @e  BLDOPT_REMOVE_C6_STATE @n
 182  *         This option removes the code which implements the C6 C-state feature.
 183  *
 184  * @anchor BLDOPT_REMOVE_MEM_RESTORE_SUPPORT
 185  * @li @e  BLDOPT_REMOVE_MEM_RESTORE_SUPPORT @n
 186  *         This option removes the memory context restore feature.
 187  *
 188  * @anchor BLDOPT_REMOVE_FAMILY_10_SUPPORT
 189  * @li @e  BLDOPT_REMOVE_FAMILY_10_SUPPORT @n
 190  *         If the package contains support for family 10h processors, remove that support.
 191  *
 192  * @anchor BLDOPT_REMOVE_FAMILY_12_SUPPORT
 193  * @li @e  BLDOPT_REMOVE_FAMILY_12_SUPPORT @n
 194  *         If the package contains support for family 10h processors, remove that support.
 195  *
 196  * @anchor BLDOPT_REMOVE_FAMILY_14_SUPPORT
 197  * @li @e  BLDOPT_REMOVE_FAMILY_14_SUPPORT @n
 198  *         If the package contains support for family 14h processors, remove that support.
 199  *
 200  * @anchor BLDOPT_REMOVE_FAMILY_15_SUPPORT
 201  * @li @e  BLDOPT_REMOVE_FAMILY_15_SUPPORT @n
 202  *         If the package contains support for family 15h processors, remove that support.
 203  *
 204  * @anchor BLDOPT_REMOVE_AM3_SOCKET_SUPPORT
 205  * @li @e  BLDOPT_REMOVE_AM3_SOCKET_SUPPORT @n
 206  *         This option removes the code which implements support for processors packaged for AM3 sockets.
 207  *
 208  * @anchor BLDOPT_REMOVE_ASB2_SOCKET_SUPPORT
 209  * @li @e  BLDOPT_REMOVE_ASB2_SOCKET_SUPPORT @n
 210  *         This option removes the code which implements support for processors packaged for ASB2 sockets.
 211  *
 212  * @anchor BLDOPT_REMOVE_C32_SOCKET_SUPPORT
 213  * @li @e  BLDOPT_REMOVE_C32_SOCKET_SUPPORT @n
 214  *         This option removes the code which implements support for processors packaged for C32 sockets.
 215  *
 216  * @anchor BLDOPT_REMOVE_FM1_SOCKET_SUPPORT
 217  * @li @e  BLDOPT_REMOVE_FM1_SOCKET_SUPPORT @n
 218  *         This option removes the code which implements support for processors packaged for FM1 sockets.
 219  *
 220  * @anchor BLDOPT_REMOVE_FP1_SOCKET_SUPPORT
 221  * @li @e  BLDOPT_REMOVE_FP1_SOCKET_SUPPORT @n
 222  *         This option removes the code which implements support for processors packaged for FP1 sockets.
 223  *
 224  * @anchor BLDOPT_REMOVE_FS1_SOCKET_SUPPORT
 225  * @li @e  BLDOPT_REMOVE_FS1_SOCKET_SUPPORT @n
 226  *         This option removes the code which implements support for processors packaged for FS1 sockets.
 227  *
 228  * @anchor BLDOPT_REMOVE_FT1_SOCKET_SUPPORT
 229  * @li @e  BLDOPT_REMOVE_FT1_SOCKET_SUPPORT @n
 230  *         This option removes the code which implements support for processors packaged for FT1 sockets.
 231  *
 232  * @anchor BLDOPT_REMOVE_G34_SOCKET_SUPPORT
 233  * @li @e  BLDOPT_REMOVE_G34_SOCKET_SUPPORT @n
 234  *         This option removes the code which implements support for processors packaged for G34 sockets.
 235  *
 236  * @anchor BLDOPT_REMOVE_S1G3_SOCKET_SUPPORT
 237  * @li @e  BLDOPT_REMOVE_S1G3_SOCKET_SUPPORT @n
 238  *         This option removes the code which implements support for processors packaged for S1G3 sockets.
 239  *
 240  * @anchor BLDOPT_REMOVE_S1G4_SOCKET_SUPPORT
 241  * @li @e  BLDOPT_REMOVE_S1G4_SOCKET_SUPPORT @n
 242  *         This option removes the code which implements support for processors packaged for S1G4 sockets.
 243  */
 244
 245 /**
 246  * @page examplecustomizations Customization Examples
 247  *
 248  * The Addendum \<plat\>Options.c file for each platform contains the minimum required
 249  * customizations for that platform.  That is, it contains settings which would be needed
 250  * to boot a SimNow! bsd for that platform.
 251  * However, each individual product based on that platform will have customizations necessary for
 252  * that hardware.  Since the actual customizations needed vary so much, they are not included in
 253  * the \<plat\>Options.c.  This section provides examples of useful customizations that you can use or
 254  * modify to suit your needs.
 255  *
 256  * @par
 257  *
 258  * Source for the examples shown can be found at Addendum\\Examples. @n
 259  *
 260  * - @ref DeemphasisExamples "Deemphasis List Examples"
 261  * - @ref FrequencyLimitExamples "Frequency Limit Examples"
 262  * - @ref PerfPerWattHt "A performance-per-watt optimization Example"
 263  *
 264  * @anchor DeemphasisExamples
 265  * @par Deemphasis List Examples
 266  *
 267  * These examples customize PLATFORM_CONFIGURATION.PlatformDeemphasisList.
 268  * Source for the deemphasis list examples can be found in DeemphasisExamples.c. @n
 269  * @dontinclude DeemphasisExamples.c
 270  * <ul>
 271  * <li>
 272  *  The following deemphasis list provides an example for a 2P MCM Max Performance configuration.
 273  *  High Speed HT frequencies are supported.  There is only one non-coherent chain.  Note the technique of
 274  *  putting specified link matches before all uses of match any.  It often works well to specify the non-coherent links
 275  *  and use match any for the coherent links.
 276  *  @skip DinarDeemphasisList
 277  *  @until {
 278  *  The non-coherent chain can run up to 2600 MHz.  The chain is located on Socket 0, package Link 2.
 279  *  @until {
 280  *  @line }
 281  *  @line {
 282  *  @line }
 283  *  The coherent links can run up to 3200 MHz.
 284  *  @until HT_FREQUENCY_MAX
 285  *  @line }
 286  *  end of list:
 287  *  @until }
 288  *  Make this list the build time customized deemphasis list.
 289  *  @line define
 290  *
 291  * </li><li>
 292  *
 293  * The following deemphasis list provides an example for a 4P MCM Max Performance configuration.
 294  * This system has a backplane with connectors for CPU cards and an IO board. So trace lengths are long.
 295  * There can be one to four IO Chains, depending on the IO board.
 296  * @skipline DoubloonDeemphasisList
 297  * @until DoubloonDeemphasisList
 298  *
 299  * </li><li>
 300  *
 301  * The following deemphasis list further illustrates complex coherent system deemphasis.  This is the same
 302  * Dinar system as in an earlier example, but this time all the coherent links are explicitly customized (as
 303  * might be needed if each link has unique characterization).  For this example, we skip the non-coherent chains.
 304  * (A real system would have to include them, see example above.)
 305  *  @skip DinarPerLinkDeemphasisList
 306  *  @until {
 307  *  Provide deemphasis settings for the 16 bit, ganged, links, Socket 0 links 0, 1 and Socket 1 links 1 and 2.
 308  *  Provide entries to customize all HT3 frequencies at which the links may run.  This example covers all HT3 speeds.
 309  *  @until {
 310  *  @until DcvLevelMinus6
 311  *  @until DcvLevelMinus6
 312  *  @until DcvLevelMinus6
 313  *  @until DcvLevelMinus6
 314  *  Link 3 on both sockets connects different internal die:  sublink 0 connects the internal node zeroes, and
 315  *  sublink 1 connects the internal node ones.  So the link is unganged and both sublinks must be specifically
 316  *  customized.
 317  *  @until {
 318  *  @until DcvLevelMinus6
 319  *  @until DcvLevelMinus6
 320  *  @until DcvLevelMinus6
 321  *  @until DcvLevelMinus6
 322  *  end of list:
 323  *  @until define
 324  *
 325  * </ul>
 326  *
 327  * @anchor FrequencyLimitExamples
 328  * @par Frequency Limit Examples
 329  *
 330  * These examples customize AMD_HT_INTERFACE.CpuToCpuPcbLimitsList and AMD_HT_INTERFACE.IoPcbLimitsList.
 331  * Source for the frequency limit examples can be found in FrequencyLimitExamples.c. @n
 332  * @dontinclude FrequencyLimitExamples.c
 333  * <ul>
 334  * <li>
 335  *    The following list provides an example for limiting all coherent links to non-extended frequencies,
 336  * that is, to 2600 MHz or less.
 337  * @skipline NonExtendedCpuToCpuLimitList
 338  * @until {
 339  *   Provide the limit customization.  Match links from any socket, any package link, to any socket, any package link. Width is not limited.
 340  * @until HT_FREQUENCY_LIMIT_2600M
 341  * End of list:
 342  * @until ;
 343  * Customize the build to use this cpu to cpu frequency limit.
 344  * @until NonExtendedCpuToCpuLimitList
 345  * @n </li>
 346  * <li>
 347  *    The following list provides an example for limiting all coherent links to HT 1 frequencies,
 348  * that is, to 1000 MHz or less.  This is sometimes useful for test and debug.
 349  * @skipline Ht1CpuToCpuLimitList
 350  * @until Ht1CpuToCpuLimitList
 351  * @n </li>
 352  * <li>
 353  *    The following list provides an example for limiting all non-coherent links to 2400 MHz or less.
 354  *    The chain is matched by host processor Socket and package Link.  The depth can be used to select a particular device
 355  *    to device link on the chain. In this example, the chain consists of a single cave device and depth can be set to match any.
 356  * @skipline No2600MhzIoLimitList
 357  * @until No2600MhzIoLimitList
 358  * @n </li>
 359  * <li>
 360  *    The following list provides an example for limiting all non-coherent links to the minimum HT 3 frequency,
 361  * that is, to 1200 MHz or less.  This can be useful for test and debug.
 362  * @skipline MinHt3IoLimitList
 363  * @until MinHt3IoLimitList
 364  * @n </li>
 365  *
 366  * </ul>
 367  *
 368  * @anchor PerfPerWattHt
 369  * @par Performance-per-Watt Optimization Example
 370  *
 371  * This example customizes AMD_HT_INTERFACE.SkipRegangList.
 372  * Source for the Performance-per-watt Optimization example can be found in PerfPerWatt.c. @n
 373  * @dontinclude PerfPerWatt.c
 374  * To implement a performance-per-watt optimization for MCM processors, use the skip regang structure shown. @n
 375  * @skipline PerfPerWatt
 376  * @until PerfPerWatt
 377  *
 378  */