src/vendorcode/amd/agesa/f15/Proc/HT/htInterface.h

   1 /* $NoKeywords:$ */
   2 /**
   3  * @file
   4  *
   5  * Internal access to HT Interface.
   6  *
   7  * This file provides definitions used by HT internal modules.  The
   8  * external HT interface (in agesa.h) is accessed using these methods.
   9  * This keeps the HT Feature implementations abstracted from the HT
  10  * interface.
  11  *
  12  * This file includes the interface access constructor and interface
  13  * support which is not removed with various build options.
  14  *
  15  * @xrefitem bom "File Content Label" "Release Content"
  16  * @e project:      AGESA
  17  * @e sub-project:  HyperTransport
  18  * @e \$Revision: 44324 $        @e  \$Date: 2010-12-22 02:16:51 -0700 (Wed, 22 Dec 2010) $
  19  *
  20  */
  21 /*
  22 *****************************************************************************
  23 *
  24 * Copyright (C) 2012 Advanced Micro Devices, Inc.
  25 * All rights reserved.
  26 *
  27 * Redistribution and use in source and binary forms, with or without
  28 * modification, are permitted provided that the following conditions are met:
  29 *     * Redistributions of source code must retain the above copyright
  30 *       notice, this list of conditions and the following disclaimer.
  31 *     * Redistributions in binary form must reproduce the above copyright
  32 *       notice, this list of conditions and the following disclaimer in the
  33 *       documentation and/or other materials provided with the distribution.
  34 *     * Neither the name of Advanced Micro Devices, Inc. nor the names of
  35 *       its contributors may be used to endorse or promote products derived
  36 *       from this software without specific prior written permission.
  37 *
  38 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  39 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  40 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  41 * DISCLAIMED. IN NO EVENT SHALL ADVANCED MICRO DEVICES, INC. BE LIABLE FOR ANY
  42 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  43 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  44 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  45 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  46 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  47 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  48 *
  49 * ***************************************************************************
  50 *
  51 */
  52
  53 #ifndef _HT_INTERFACE_H_
  54 #define _HT_INTERFACE_H_
  55
  56 /**
  57  * @page htimplintf HT Internal Interface Implementation Guide
  58  *
  59  * HT Internal Interface provides access to the HT Component external interface (see AGESA.h),
  60  * in a manner that isolates calling code from knowledge about the external interface or which
  61  * interfaces are supported in the current build.
  62  *
  63  * @par Adding a Method to HT Internal Interface
  64  *
  65  * To add a new method to the HT Internal Interface, follow these steps.
  66  * <ul>
  67  * <li> Create a typedef for the Method with the correct parameters and return type.
  68  *
  69  *   <ul>
  70  *   <li> Name the method typedef (F_METHOD_NAME)(), where METHOD_NAME is the same name as the method table item,
  71  *     but with "_"'s and UPPERCASE, rather than mixed case.
  72  *     @n <tt> typedef VOID (F_METHOD_NAME)(); </tt> @n
  73  *
  74  *   <li> Make a reference type for references to a method implementation:
  75  *     @n <tt> /// Reference to a Method              </tt>
  76  *     @n <tt> typedef F_METHOD_NAME *PF_METHOD_NAME  </tt> @n
  77  *   </ul>
  78  *
  79  * <li> Provide a standard doxygen function preamble for the Method typedef. Begin the
  80  *   detailed description by providing a reference to the method instances page by including
  81  *   the lines below:
  82  *   @code
  83  *   *
  84  *   * @HtInterfaceInstances
  85  *   *
  86  *   @endcode
  87  *   @note It is important to provide documentation for the method type, because the method may not
  88  *   have an implementation in any families supported by the current package. @n
  89  *
  90  * <li> Add to the HT_INTERFACE struct an item for the Method:
  91  *   @n <tt>  PF_METHOD_NAME MethodName; ///< Method: description. </tt> @n
  92  * </ul>
  93  *
  94  * @par Implementing an HT Internal Interface Instance of the method.
  95  *
  96  * To implement an instance of a method for a specific interface  follow these steps.
  97  *
  98  * - In appropriate files, implement the method with the return type and parameters
  99  * matching the method typedef.
 100  *
 101  * - Name the function MethodName().
 102  *
 103  * - Create a doxygen function preamble for the method instance.  Begin the detailed description with
 104  *   an Implements command to reference the method type and add this instance to the Method Instances page.
 105  *   @code
 106  *   *
 107  *   *  @HtInterfaceMethod{::F_METHOD_NAME}.
 108  *   *
 109  *   @endcode
 110  *
 111  * - To access other Ht internal interface routines or data as part of the method implementation, the function
 112  *   must use HtInterface->OtherMethod().  Do not directly access other HT internal interface
 113  *   routines, because in the table there may be overrides or this routine may be shared by multiple families.
 114  *
 115  * - Add the instance to the HT_INTERFACE instances.
 116  *
 117  * - If a configuration does not need an instance of the method use one of the CommonReturns from
 118  *   CommonReturns.h with the same return type.
 119  *
 120  * @par Invoking HT Internal Interface Methods.
 121  *
 122  * The first step is carried out only once by the top level HT entry point.
 123  * @n @code
 124  *   HT_INTERFACE HtInterface;
 125  *   // Get the current HT internal interface (to HtBlock data)
 126  *   NewHtInterface (&HtInterface);
 127  *   State->HtInterface = &HtInterface;
 128  * @endcode
 129  *
 130  * The following example shows how to invoke a HT Internal Interface method.
 131  * @n @code
 132  *    State->HtInterface->MethodName ();
 133  * @endcode
 134  *
 135  */
 136
 137 /*----------------------------------------------------------------------------
 138  *   Mixed (DEFINITIONS AND MACROS / TYPEDEFS, STRUCTURES, ENUMS)
 139  *
 140  *----------------------------------------------------------------------------
 141  */
 142
 143 /*-----------------------------------------------------------------------------
 144  *                         DEFINITIONS AND MACROS
 145  *
 146  *-----------------------------------------------------------------------------
 147  */
 148
 149 /*----------------------------------------------------------------------------
 150  *                         TYPEDEFS, STRUCTURES, ENUMS
 151  *
 152  *----------------------------------------------------------------------------
 153  */
 154
 155 /**
 156  * Get limits for CPU to CPU Links.
 157  *
 158  * @HtInterfaceInstances.
 159  *
 160  * @param[in]     NodeA            One Node on which this Link is located
 161  * @param[in]     LinkA            The Link on this Node
 162  * @param[in]     NodeB            The other Node on which this Link is located
 163  * @param[in]     LinkB            The Link on that Node
 164  * @param[in,out] ABLinkWidthLimit modify to change the Link Width In
 165  * @param[in,out] BALinkWidthLimit modify to change the Link Width Out
 166  * @param[in,out] PcbFreqCap       modify to change the Link's frequency capability
 167  * @param[in]     State            the input data
 168  *
 169  */
 170 typedef VOID F_GET_CPU_2_CPU_PCB_LIMITS (
 171   IN       UINT8        NodeA,
 172   IN       UINT8        LinkA,
 173   IN       UINT8        NodeB,
 174   IN       UINT8        LinkB,
 175   IN OUT   UINT8        *ABLinkWidthLimit,
 176   IN OUT   UINT8        *BALinkWidthLimit,
 177   IN OUT   UINT32       *PcbFreqCap,
 178   IN       STATE_DATA   *State
 179   );
 180 /// Reference to a method.
 181 typedef F_GET_CPU_2_CPU_PCB_LIMITS *PF_GET_CPU_2_CPU_PCB_LIMITS;
 182
 183 /**
 184  * Skip reganging of subLinks.
 185  *
 186  * @HtInterfaceInstances.
 187  *
 188  * @param[in]     NodeA    One Node on which this Link is located
 189  * @param[in]     LinkA    The Link on this Node
 190  * @param[in]     NodeB    The other Node on which this Link is located
 191  * @param[in]     LinkB    The Link on that Node
 192  * @param[in]     State    the input data
 193  *
 194  * @retval        MATCHED      leave Link unganged
 195  * @retval        POWERED_OFF  leave link unganged and power off the paired sublink
 196  * @retval        UNMATCHED    regang Link automatically
 197  */
 198 typedef FINAL_LINK_STATE F_GET_SKIP_REGANG (
 199   IN       UINT8        NodeA,
 200   IN       UINT8        LinkA,
 201   IN       UINT8        NodeB,
 202   IN       UINT8        LinkB,
 203   IN       STATE_DATA   *State
 204   );
 205 /// Reference to a method.
 206 typedef F_GET_SKIP_REGANG *PF_GET_SKIP_REGANG;
 207
 208 /**
 209  * Manually control bus number assignment.
 210  *
 211  * @HtInterfaceInstances.
 212  *
 213  * @param[in]     Node      The Node on which this chain is located
 214  * @param[in]     Link      The Link on the host for this chain
 215  * @param[out]    SecBus    Secondary Bus number for this non-coherent chain
 216  * @param[out]    SubBus    Subordinate Bus number
 217  * @param[in]     State     the input data
 218  *
 219  * @retval        TRUE      this routine is supplying the bus numbers
 220  * @retval        FALSE     use auto Bus numbering
 221  */
 222 typedef BOOLEAN F_GET_OVERRIDE_BUS_NUMBERS (
 223   IN       UINT8        Node,
 224   IN       UINT8        Link,
 225      OUT   UINT8        *SecBus,
 226      OUT   UINT8        *SubBus,
 227   IN       STATE_DATA   *State
 228   );
 229 /// Reference to a method.
 230 typedef F_GET_OVERRIDE_BUS_NUMBERS *PF_GET_OVERRIDE_BUS_NUMBERS;
 231
 232 /**
 233  * Get Manual BUID assignment list.
 234  *
 235  * @HtInterfaceInstances.
 236  *
 237  * @param[in]    Node    The Node on which this chain is located
 238  * @param[in]    Link    The Link on the host for this chain
 239  * @param[out]   List    a pointer to a list, if returns TRUE
 240  * @param[in]    State   the input data
 241  *
 242  * @retval      TRUE     use manual List
 243  * @retval      FALSE    initialize the Link automatically. List not valid.
 244  */
 245 typedef BOOLEAN F_GET_MANUAL_BUID_SWAP_LIST (
 246   IN       UINT8            Node,
 247   IN       UINT8            Link,
 248      OUT   BUID_SWAP_LIST   **List,
 249   IN       STATE_DATA       *State
 250   );
 251 /// Reference to a method.
 252 typedef F_GET_MANUAL_BUID_SWAP_LIST *PF_GET_MANUAL_BUID_SWAP_LIST;
 253
 254 /**
 255  * Override capabilities of a device.
 256  *
 257  * @HtInterfaceInstances.
 258  *
 259  * @param[in]     HostNode      The Node on which this chain is located
 260  * @param[in]     HostLink      The Link on the host for this chain
 261  * @param[in]     Depth         The Depth in the I/O chain from the Host
 262  * @param[in]     PciAddress    The Device's PCI config address (for callout)
 263  * @param[in]     DevVenId      The Device's PCI Vendor + Device ID (offset 0x00)
 264  * @param[in]     Revision      The Device's PCI Revision
 265  * @param[in]     Link          The Device's Link number (0 or 1)
 266  * @param[in,out] LinkWidthIn   modify to change the Link Width In
 267  * @param[in,out] LinkWidthOut  modify to change the Link Width Out
 268  * @param[in,out] FreqCap       modify to change the Link's frequency capability
 269  * @param[in,out] Clumping      modify to change unit id clumping capability
 270  * @param[in]     State         the input data
 271  *
 272  */
 273 typedef VOID F_GET_DEVICE_CAP_OVERRIDE (
 274   IN       UINT8       HostNode,
 275   IN       UINT8       HostLink,
 276   IN       UINT8       Depth,
 277   IN       PCI_ADDR    PciAddress,
 278   IN       UINT32      DevVenId,
 279   IN       UINT8       Revision,
 280   IN       UINT8       Link,
 281   IN OUT   UINT8       *LinkWidthIn,
 282   IN OUT   UINT8       *LinkWidthOut,
 283   IN OUT   UINT32      *FreqCap,
 284   IN OUT   UINT32      *Clumping,
 285   IN       STATE_DATA  *State
 286   );
 287 /// Reference to a method.
 288 typedef F_GET_DEVICE_CAP_OVERRIDE *PF_GET_DEVICE_CAP_OVERRIDE;
 289
 290 /**
 291  * Get limits for non-coherent Links.
 292  *
 293  * @HtInterfaceInstances.
 294  *
 295  * @param[in]     HostNode                   The Node on which this Link is located
 296  * @param[in]     HostLink                   The Link about to be initialized
 297  * @param[in]     Depth                      The Depth in the I/O chain from the Host
 298  * @param[in,out] DownstreamLinkWidthLimit   modify to change the Link Width In
 299  * @param[in,out] UpstreamLinkWidthLimit     modify to change the Link Width Out
 300  * @param[in,out] PcbFreqCap                 modify to change the Link's frequency capability
 301  * @param[in]     State                      the input data
 302  */
 303 typedef VOID F_GET_IO_PCB_LIMITS (
 304   IN       UINT8        HostNode,
 305   IN       UINT8        HostLink,
 306   IN       UINT8        Depth,
 307   IN OUT   UINT8        *DownstreamLinkWidthLimit,
 308   IN OUT   UINT8        *UpstreamLinkWidthLimit,
 309   IN OUT   UINT32       *PcbFreqCap,
 310   IN       STATE_DATA   *State
 311   );
 312 /// Reference to a method.
 313 typedef F_GET_IO_PCB_LIMITS *PF_GET_IO_PCB_LIMITS;
 314
 315 /**
 316  * Get the Socket number for a given Node number.
 317  *
 318  * @HtInterfaceInstances.
 319  *
 320  * @param[in]     Node    Node discovered event data.
 321  * @param[in]     State   reference to Node to socket map
 322  *
 323  * @return the socket id
 324  *
 325  */
 326 typedef UINT8 F_GET_SOCKET_FROM_MAP (
 327   IN       UINT8         Node,
 328   IN       STATE_DATA    *State
 329   );
 330 /// Reference to a method.
 331 typedef F_GET_SOCKET_FROM_MAP *PF_GET_SOCKET_FROM_MAP;
 332
 333 /**
 334  * Ignore a Link.
 335  *
 336  * @HtInterfaceInstances.
 337  *
 338  * @param[in]     Node   The Node on which this Link is located
 339  * @param[in]     Link   The Link about to be initialized
 340  * @param[in]     NbList The northbridge default ignore link list
 341  * @param[in]     State   the input data
 342  *
 343  * @retval        MATCHED     ignore this Link and skip it
 344  * @retval        POWERED_OFF ignore this link and power it off.
 345  * @retval        UNMATCHED   initialize the Link normally
 346  */
 347 typedef FINAL_LINK_STATE F_GET_IGNORE_LINK (
 348   IN       UINT8        Node,
 349   IN       UINT8        Link,
 350   IN       IGNORE_LINK  *NbIgnoreLinkList,
 351   IN       STATE_DATA   *State
 352   );
 353 /// Reference to a method.
 354 typedef F_GET_IGNORE_LINK *PF_GET_IGNORE_LINK;
 355
 356 /**
 357  * Post Node id and other context info to AP cores via mailbox.
 358  *
 359  * @HtInterfaceInstances.
 360  *
 361  * @param[in] State Our state
 362  */
 363 typedef VOID F_POST_MAP_TO_AP (
 364   IN       STATE_DATA *State
 365   );
 366 /// Reference to a method.
 367 typedef F_POST_MAP_TO_AP *PF_POST_MAP_TO_AP;
 368
 369 /**
 370  * Clean up the map structures after severe event has caused a fall back to 1 node.
 371  *
 372  * @HtInterfaceInstances.
 373  *
 374  * @param[in] State Our state
 375  */
 376 typedef VOID F_CLEAN_MAPS_AFTER_ERROR (
 377   IN       STATE_DATA *State
 378   );
 379 /// Reference to a method.
 380 typedef F_CLEAN_MAPS_AFTER_ERROR *PF_CLEAN_MAPS_AFTER_ERROR;
 381
 382 /**
 383  * Get a new Socket Die to Node Map.
 384  *
 385  * @HtInterfaceInstances.
 386  *
 387  * @param[in,out] State global state
 388  */
 389 typedef VOID F_NEW_NODE_AND_SOCKET_TABLES (
 390   IN OUT   STATE_DATA *State
 391   );
 392 /// Reference to a method.
 393 typedef F_NEW_NODE_AND_SOCKET_TABLES *PF_NEW_NODE_AND_SOCKET_TABLES;
 394
 395 /**
 396  * Fill in the socket's Node id when a processor is discovered in that socket.
 397  *
 398  * @HtInterfaceInstances.
 399  *
 400  * @param[in] Node                Node from which a new node was discovered
 401  * @param[in] CurrentNodeModule   The current node's module id in it's processor.
 402  * @param[in] PackageLink         The package level link from Node to NewNode.
 403  * @param[in] NewNode             The new node's id
 404  * @param[in] HardwareSocket      If we use the hardware method (preferred), this is the socket of new node.
 405  * @param[in] Module              The new node's module id in it's processor.
 406  * @param[in] State               our State
 407  */
 408 typedef VOID F_SET_NODE_TO_SOCKET_MAP (
 409   IN       UINT8 Node,
 410   IN       UINT8 CurrentNodeModule,
 411   IN       UINT8 PackageLink,
 412   IN       UINT8 NewNode,
 413   IN       UINT8 HardwareSocket,
 414   IN       UINT8 Module,
 415   IN       STATE_DATA *State
 416   );
 417 /// Reference to a method.
 418 typedef F_SET_NODE_TO_SOCKET_MAP *PF_SET_NODE_TO_SOCKET_MAP;
 419
 420 /**
 421  * Get a new, empty Hop Count Table, to make one for the installed topology.
 422  *
 423  * @HtInterfaceInstances.
 424  *
 425  * @param[in,out]   State    Keep our buffer handle.
 426  *
 427  */
 428 typedef VOID F_NEW_HOP_COUNT_TABLE (
 429   IN OUT   STATE_DATA     *State
 430   );
 431 /// Reference to a method.
 432 typedef F_NEW_HOP_COUNT_TABLE *PF_NEW_HOP_COUNT_TABLE;
 433
 434 /**
 435  * Get the minimum Northbridge frequency for the system.
 436  *
 437  * @HtInterfaceInstances.
 438  *
 439  * Invoke the CPU component power mgt interface.
 440  *
 441  * @param[in]    PlatformConfig   Platform profile/build option config structure.
 442  * @param[in]    StdHeader        Config for library and services.
 443  *
 444  * @return Frequency in MHz.
 445  *
 446  */
 447 typedef UINT32 F_GET_MIN_NB_CORE_FREQ (
 448   IN       PLATFORM_CONFIGURATION *PlatformConfig,
 449   IN       AMD_CONFIG_PARAMS      *StdHeader
 450   );
 451 /// Reference to a Method.
 452 typedef F_GET_MIN_NB_CORE_FREQ *PF_GET_MIN_NB_CORE_FREQ;
 453
 454 /**
 455  * The HT Interface, feature code uses these methods to get interface parameters.
 456  */
 457 struct _HT_INTERFACE {                                // See Forward Declaration in HtFeates.h
 458   PF_GET_CPU_2_CPU_PCB_LIMITS GetCpu2CpuPcbLimits;    /**< Method: Get link limits for coherent links. */
 459   PF_GET_SKIP_REGANG GetSkipRegang;                   /**< Method: Skip reganging for coherent links. */
 460   PF_NEW_HOP_COUNT_TABLE NewHopCountTable;            /**< Method: Get a new hop count table. */
 461   PF_GET_OVERRIDE_BUS_NUMBERS GetOverrideBusNumbers;  /**< Method: Control Bus number assignment. */
 462   PF_GET_MANUAL_BUID_SWAP_LIST GetManualBuidSwapList; /**< Method: Assign device IDs. */
 463   PF_GET_DEVICE_CAP_OVERRIDE GetDeviceCapOverride;    /**< Method: Override Device capabilities. */
 464   PF_GET_IO_PCB_LIMITS GetIoPcbLimits;                /**< Method: Get link limits for noncoherent links. */
 465   PF_GET_SOCKET_FROM_MAP GetSocketFromMap;            /**< Method: Get the Socket for a node id. */
 466   PF_GET_IGNORE_LINK GetIgnoreLink;                   /**< Method: Ignore a link. */
 467   PF_POST_MAP_TO_AP PostMapToAp;                      /**< Method: Post Socket and other info to AP cores. */
 468   PF_NEW_NODE_AND_SOCKET_TABLES NewNodeAndSocketTables; /**< Method: Get new socket and node maps. */
 469   PF_CLEAN_MAPS_AFTER_ERROR CleanMapsAfterError;       /**< Method: Clean up maps for forced 1P on error fall back. */
 470   PF_SET_NODE_TO_SOCKET_MAP SetNodeToSocketMap;       /**< Method: Associate a node id with a socket. */
 471   PF_GET_MIN_NB_CORE_FREQ GetMinNbCoreFreq;           /**< Method: Get the minimum northbridge frequency */
 472 } ;
 473
 474 /*----------------------------------------------------------------------------
 475  *                         Prototypes to Interface from Feature Code
 476  *
 477  *----------------------------------------------------------------------------
 478  */
 479
 480 /**
 481  * A constructor for the internal Ht Interface.
 482  *
 483 */
 484 VOID
 485 NewHtInterface (
 486      OUT   HT_INTERFACE         *HtInterface,
 487   IN       AMD_CONFIG_PARAMS    *StdHeader
 488   );
 489
 490 #endif  /* _HT_INTERFACE_H_ */