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