blob: 0a49fed757277cdfba2ca245faa2a8311bf18b3a [file] [log] [blame]
efdesign98b0969d62011-06-16 16:35:54 -07001/* $NoKeywords:$ */
2/**
3 * @file
4 *
5 * Create outline and references for 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 * @mainpage
49 *
50 * The design and maintenance documentation for AGESA Sample Code is organized as
51 * follows. On this page, you can reference design guides, maintenance guides, and
52 * general documentation. Detailed Data Structure, Function, and Interface documentation
53 * may be found using the Data Structures or Files tabs. See Related Pages for a
54 * Release content summary, and, if this is not a production release, lists of To Do's,
55 * Deprecated items, etc.
56 *
57 * @subpage starthere "Start Here - Initial Porting and Integration."
58 *
59 * @subpage optionmain "Build Configuration and Options Guides and Documentation."
60 *
61 * @subpage commonmain "Processor Common Component Guides and Documentation."
62 *
63 * @subpage cpumain "CPU Component Guides and Documentation."
64 *
65 * @subpage htmain "HT Component Guides and Documentation."
66 *
67 * @subpage memmain "MEM Component Guides and Documentation."
68 *
69 * @subpage gnbmain "GNB Component Documentation."
70 *
71 * @subpage idsmain "IDS Component Guides and Documentation."
72 *
73 * @subpage recoverymain "Recovery Component Guides and Documentation."
74 *
75 */
76
77/**
78 * @page starthere Initial Porting and Integration
79 *
80 * @par Basic Check List
81 *
82 * <ul>
83 * <li> Copy the \<plat\>Options.c file from the Addendum directory to the platform tip build directory.
84 * AMD recommends the use of a sub-directory named AGESA to contain these files and the build output files.
85 * <li> Copy the OptionsIds.h content in the spec to OptionsIds.h in the platform build tip directory
86 * and make changes to enable the IDS support desired. It is highly recommended to set the following for
87 * initial integration and development:@n
88 * @code
89 * #define IDSOPT_IDS_ENABLED TRUE
90 * #define IDSOPT_ERROR_TRAP_ENABLED TRUE
91 * #define IDSOPT_ASSERT_ENABLED TRUE
92 * @endcode
93 * <li> Edit and modify the option selections in those two files to meet the needs of the specific platform.
94 * <li> Set the environment variable AGESA_ROOT to the root folder of the AGESA code.
95 * <li> Set the environment variable AGESA_OptsDir the platform build tip AGESA directory.
96 * <li> Generate the doxygen documentation or locate the file arch2008.chm within your AGESA release package.
97 * </ul>
98 *
99 * @par Debugging Using ASSERT and IDS_ERROR_TRAP
100 *
101 * While AGESA code uses ::ASSERT and ::IDS_ERROR_TRAP to check for internal errors, these macros can also
102 * catch and assist debug of wrapper and platform BIOS issues.
103 *
104 * When an ::ASSERT fails or an ::IDS_ERROR_TRAP is executed, the AGESA code will enter a halt loop and display a
105 * Stop Code. A Stop Code is eight hex digits. The first (most significant) four are the FILECODE.
106 * FILECODEs can be looked up in Filecode.h to determine which file contains the stop macro. Each file has a
107 * unique code value.
108 * The least significant digits are the line number in that file.
109 * For example, 0210 means the macro is on line two hundred ten.
110 * (see ::IdsErrorStop for more details on stop code display.)
111 *
112 * Enabling ::ASSERT and ::IDS_ERROR_TRAP ensure errors are caught and also provide a useful debug assist.
113 * Comments near each macro use will describe the nature of the error and typical wrapper errors or other
114 * root causes.
115 *
116 * After your wrapper consistently executes ::ASSERT and ::IDS_ERROR_TRAP stop free, you can disable them in
117 * OptionsIds.h, except for regression testing. IDS is not expected to be enabled in production BIOS builds.
118 *
119 */