Gitiles
Code Review Sign In
review.coreboot.org / coreboot / a50ced2eba20a007fa5b486c251c252ad09868cf / . / Documentation / Intel / development.html
blob: a2ba2781e0ef4b8ed0bdf3f6a408109e6c96f0d2 [file] [log] [blame]
Lee Leahyc1e4f892016-01-07 11:24:24 -0800[diff] [blame]1<!DOCTYPE html>
2<html>
3 <head>
4 <title>Development</title>
5 </head>
6 <body>
7
Lee Leahye8424cf2016-02-03 07:28:22 -0800[diff] [blame]8<h1>Intel&reg; x86 coreboot/FSP Development Process</h1>
Lee Leahyc1e4f892016-01-07 11:24:24 -0800[diff] [blame]9<p>
10 The x86 development process for coreboot is broken into the following components:
11</p>
12<ul>
Lee Leahye8424cf2016-02-03 07:28:22 -0800[diff] [blame]13 <li>coreboot <a target="_blank" href="SoC/soc.html">SoC</a> development</li>
14 <li>coreboot <a target="_blank" href="Board/board.html">mainboard</a> development</li>
Lee Leahyc1e4f892016-01-07 11:24:24 -0800[diff] [blame]15 <li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration</li>
16</ul>
17<p>
18 The development process has two main phases:
19</p>
20<ol>
21 <li>Minimal coreboot; This phase is single threaded</li>
22 <li>Adding coreboot features</li>
23</ol>
24
Lee Leahye8424cf2016-02-03 07:28:22 -0800[diff] [blame]25<h2>Minimal coreboot</h2>
Lee Leahyc1e4f892016-01-07 11:24:24 -0800[diff] [blame]26<p>
27 The combined steps below describe how to bring up a minimal coreboot for a
28 system-on-a-chip (SoC) and a development board:
29</p>
30<table>
31 <tr bgcolor="#ffffc0">
32 <td>The initial coreboot steps are single threaded!
33 The initial minimal FSP development is also single threaded.
34 Progress can speed up by adding more developers after the minimal coreboot/FSP
35 implementation reaches the payload.
36 </td>
37 </tr>
38</table>
39<ol>
40 <li>Get the necessary tools:
41 <ul>
42 <li>Linux: Use your package manager to install m4 bison flex and the libcurses development
43 package.
44 <ul>
45 <li>Ubuntu or other Linux distribution that use apt, run:
46<pre><code>sudo apt-get install m4 bison flex libncurses5-dev
47</code></pre>
48 </li>
49 </ul>
50 </li>
51 </ul>
52 </li>
53 <li>Build the cross tools for i386:
54 <ul>
55 <li>Linux:
56<pre><code>make crossgcc-i386</code></pre>
57 To use multiple processors for the toolchain build (which takes a long time), use:
58<pre><code>make crossgcc-i386 CPUS=N</code></pre>
59 where N is the number of cores to use for the build.
60 </li>
61 </ul>
62 </li>
63 <li>Get something to build:
64 <ol type="A">
65 <li><a target="_blank" href="fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li>
66 <li><a target="_blank" href="SoC/soc.html#RequiredFiles">SoC</a> required files</li>
67 <li><a target="_blank" href="Board/board.html#RequiredFiles">Board</a> required files</li>
68 </ol>
69 </li>
70 <li>Get result to start <a target="_blank" href="SoC/soc.html#Descriptor">booting</a></li>
71 <li><a target="_blank" href="SoC/soc.html#EarlyDebug">Early Debug</a></li>
Lee Leahy380e1672016-01-31 10:49:35 -0800[diff] [blame]72 <li>Implement and debug the <a target="_blank" href="SoC/soc.html#Bootblock">bootblock</a> code</li>
Lee Leahy7e0078b2016-01-31 11:48:15 -0800[diff] [blame]73 <li>Implement and debug the call to <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></li>
Lee Leahy66decf12016-02-04 11:21:33 -0800[diff] [blame]74 <li>Enable the serial port
75 <ol type="A">
76 <li>Power on, enable and configure GPIOs for the
77 <a target="_blank" href="Board/board.html#SerialOutput">debug serial UART</a>
78 </li>
79 <li>Add the <a target="_blank" href="SoC/soc.html#SerialOutput">serial outupt</a>
80 support to romstage
81 </li>
82 </ol>
83 </li>
84 <li>Enable <a target="_blank" href="fsp1_1.html#corebootFspDebugging">coreboot/FSP</a> debugging</li>
Lee Leahyfcf776f2016-02-04 11:23:36 -0800[diff] [blame]85 <li>Determine the <a target="_blank" href="SoC/soc.html#PreviousSleepState">Previous Sleep State</a></li>
86 <li>Enable DRAM:
87 <ol type="A">
88 <li>Implement the SoC
89 <a target="_blank" href="SoC/soc.html#MemoryInit">MemoryInit</a>
90 Support
91 </li>
92 <li>Implement the board support to read the
93 <a target="_blank" href="Board/board.html#SpdData">Memory Timing Data</a>
94 </li>
95 </ol>
96 </li>
Lee Leahye9a6d1a2016-01-31 11:28:06 -0800[diff] [blame]97 <li>Disable the
98 <a target="_blank" href="SoC/soc.html#DisableShadowRom">Shadow ROM</a>
99 </li>
Lee Leahya4d81802016-01-31 12:19:13 -0800[diff] [blame]100 <li>Enable CONFIG_DISPLAY_MTRRS to verify the MTRR configuration</li>
Lee Leahyde8c7e32016-02-14 14:55:29 -0800[diff] [blame]101 <li>
102 Implement the .init routine for the
103 <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a>
104 structure which calls FSP SiliconInit
105 </li>
106 <li>
107 Start ramstage's
108 <a target="_blank" href="SoC/soc.html#DeviceTree">device tree processing</a>
109 to display the PCI vendor and device IDs
110 </li>
111 <li>
112 Disable the
113 <a target="_blank" href="Board/board.html#DisablePciDevices">PCI devices</a>
114 </li>
115 <li>
116 Implement the
117 <a target="_blank" href="SoC/soc.html#MemoryMap">memory map</a>
118 </li>
Lee Leahya4d81802016-01-31 12:19:13 -0800[diff] [blame]119 <li>coreboot should now attempt to load the payload</li>
Lee Leahyc1e4f892016-01-07 11:24:24 -0800[diff] [blame]120</ol>
121
122
Lee Leahy7e0078b2016-01-31 11:48:15 -0800[diff] [blame]123
Lee Leahybf08da22016-02-20 17:48:35 -0800[diff] [blame]124<h2>Add coreboot Features</h2>
125<p>
126 Most of the coreboot development gets done in this phase. Implementation tasks in this
127 phase are easily done in parallel.
128</p>
129<ul>
130 <li>Payload and OS Features:
131 <ul>
132 <li><a target="_blank" href="SoC/soc.html#AcpiTables">ACPI Tables</a></li>
Lee Leahy4ee073d2016-02-28 06:22:47 -0800[diff] [blame]133 <li><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</li>
Lee Leahybf08da22016-02-20 17:48:35 -0800[diff] [blame]134 </ul>
135 </li>
136</ul>
137
138
139
Lee Leahy7e0078b2016-01-31 11:48:15 -0800[diff] [blame]140<hr>
141<table border="1">
142 <tr bgcolor="#c0ffc0">
143 <th colspan=3><h1>Features</h1></th>
144 </tr>
145 <tr bgcolor="#c0ffc0">
146 <th>SoC</th>
147 <th>Where</th>
148 <th>Testing</th>
149 </tr>
150 <tr>
Lee Leahy4ee073d2016-02-28 06:22:47 -0800[diff] [blame]151 <td>8254 Programmable Interval Timer</td>
152 <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
153 <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
154 </tr>
155 <tr>
156 <td>8259 Programmable Interrupt Controller</td>
157 <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
158 <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
159 </tr>
160 <tr>
Lee Leahy7e0078b2016-01-31 11:48:15 -0800[diff] [blame]161 <td>Cache-as-RAM</td>
162 <td>
163 <a target="_blank" href="SoC/soc.html#TempRamInit">Find</a>
164 FSP binary:
165 <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l38">cache_as_ram.inc</a><br>
166 Enable: FSP 1.1 <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a>
167 called from
168 <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">cache_as_ram.inc</a><br>
169 Disable: FSP 1.1 TempRamExit called from
170 <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
171 </td>
172 <td>FindFSP: POST code 0x90
173 (<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
174 is displayed<br>
175 Enable: POST code
176 <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
177 is displayed<br>
178 Disable: CONFIG_DISPLAY_MTRRS=y, MTRRs displayed after call to TempRamExit
179 </td>
180 </tr>
Lee Leahyde8c7e32016-02-14 14:55:29 -0800[diff] [blame]181 <tr>
182 <td>Memory Map</td>
183 <td>
184 Implement a device driver for the
185 <a target="_blank" href="SoC/soc.html#MemoryMap">north cluster</a>
186 </td>
187 <td>coreboot displays the memory map correctly during the BS_WRITE_TABLES state</td>
188 </tr>
189 <tr>
Lee Leahya4d81802016-01-31 12:19:13 -0800[diff] [blame]190 <td>MTRRs</td>
191 <td>
192 Set values: src/drivers/intel/fsp1_1/stack.c/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/stack.c;hb=HEAD#l42">setup_stack_and_mtrrs</a><br>
193 Load values: src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l71">after_raminit.S</a>
194 </td>
195 <td>Set: Post code 0x91
196 (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l213">POST_FSP_TEMP_RAM_EXIT</a>)
197 is displayed by
198 <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
199 Load: Post code 0x3C is displayed by
200 <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l152">after_raminit.S</a><br>
201 and CONFIG_DISPLAY_MTRRS=y displays the correct memory regions</td>
202 </tr>
203 <tr>
Lee Leahyde8c7e32016-02-14 14:55:29 -0800[diff] [blame]204 <td>PCI Device Support</td>
205 <td>Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a></td>
206 <td>The device is detected by coreboot and usable by the payload</td>
207 </tr>
208 <tr>
209 <td>Ramstage state machine</td>
210 <td>
211 Implement the chip and domain operations to start the
212 <a target="_blank" href="SoC/soc.html#DeviceTree">device tree</a>
213 processing
214 </td>
215 <td>
216 During the BS_DEV_ENUMERATE state, ramstage now display the device IDs
217 for the PCI devices on the bus.
218 </td>
219 </tr>
Lee Leahye9a6d1a2016-01-31 11:28:06 -0800[diff] [blame]220 <tr>
221 <td>ROM Shadow<br>0x000E0000 - 0x000FFFFF</td>
222 <td>
223 Disable: src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/romstage/romstage.c/<a target="_blank" href="SoC/soc.html#DisableShadowRom">soc_after_ram_init routine</a>
224 </td>
225 <td>Operates as RAM: Writes followed by a read to the 0x000E0000 - 0x000FFFFF region returns the value written</td>
226 </tr>
Lee Leahy66decf12016-02-04 11:21:33 -0800[diff] [blame]227
228
229 <tr bgcolor="#c0ffc0">
230 <th>Board</th>
231 <th>Where</th>
232 <th>Testing</th>
233 </tr>
234 <tr>
Lee Leahyde8c7e32016-02-14 14:55:29 -0800[diff] [blame]235 <td>Device Tree</td>
236 <td>
237 <a target="_blank" href="SoC/soc.html#DeviceTree">List</a> PCI vendor and device IDs by starting
238 the device tree processing<br>
239 <a target="_blank" href="Board/board.html#DisablePciDevices">Disable</a> PCI devices<br>
240 Enable: Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a>
241 <td>
242 List: BS_DEV_ENUMERATE state displays PCI vendor and device IDs<br>
243 Disable: BS_DEV_ENUMERATE state shows the devices as disabled<br>
244 Enable: BS_DEV_ENUMERATE state shows the device as on and the device works for the payload
245 </td>
246 </tr>
247 <tr>
Lee Leahyfcf776f2016-02-04 11:23:36 -0800[diff] [blame]248 <td>DRAM</td>
249 <td>
250 Load SPD data: src/soc/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/spd/<a target="_blank" href="Board/board.html#SpdData">spd.c</a><br>
251 UPD Setup:
252 <ul>
253 <li>src/soc&lt;Vendor&gt;//&lt;Chip Family&gt;/romstage/<a target="_blank" href="SoC/soc.html#MemoryInit">romstage.c</a></li>
254 <li>src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/<a target="_blank" href="Board/board.html#SpdData">romstage.c</a></li>
255 </ul>
256 FSP 1.1 MemoryInit called from src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l126">raminit.c</a>
257 </td>
258 <td>Select the following Kconfig values
259 <ul>
260 <li>DISPLAY_HOBS</li>
261 <li>DISPLAY_UPD_DATA</li>
262 </ul>
263 Testing successful if:
264 <ul>
265 <li>MemoryInit UPD values are correct</li>
266 <li>MemoryInit returns 0 (success) and</li>
267 <li>The the message "ERROR - coreboot's requirements not met by FSP binary!"
268 is not displayed
269 </li>
270 </ul>
271 </td>
272 </tr>
273 <tr>
Lee Leahy66decf12016-02-04 11:21:33 -0800[diff] [blame]274 <td>Serial Port</td>
275 <td>
276 SoC <a target="_blank" href="SoC/soc.html#SerialOutput">Support</a><br>
277 Enable: src/soc/mainboard/&lt;Board&gt;/com_init.c/<a target="_blank" href="Board/board.html#SerialOutput">car_mainboard_pre_console_init</a>
278 </td>
279 <td>Debug serial output works</td>
280 </tr>
281
282
Lee Leahy7e0078b2016-01-31 11:48:15 -0800[diff] [blame]283 <tr bgcolor="#c0ffc0">
Lee Leahybf08da22016-02-20 17:48:35 -0800[diff] [blame]284 <th>Payload</th>
285 <th>Where</th>
286 <th>Testing</th>
287 </tr>
288 <tr>
289 <td>ACPI Tables</td>
290 <td>
291 SoC <a target="_blank" href="SoC/soc.html#AcpiTables">Support</a><br>
292 </td>
293 <td>Verified by payload or OS</td>
294 </tr>
295
296
297 <tr bgcolor="#c0ffc0">
Lee Leahy7e0078b2016-01-31 11:48:15 -0800[diff] [blame]298 <th>FSP</th>
299 <th>Where</th>
300 <th>Testing</th>
301 </tr>
302 <tr>
303 <td>TempRamInit</td>
304 <td>FSP <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></td>
305 <td>FSP binary found: POST code 0x90
306 (<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
307 is displayed<br>
308 TempRamInit successful: POST code
309 <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
310 is displayed<br>
311 </td>
312 </tr>
Lee Leahyfcf776f2016-02-04 11:23:36 -0800[diff] [blame]313 <tr>
314 <td>MemoryInit</td>
315 <td><a target="_blank" href="SoC/soc.html#MemoryInit">SoC</a> support<br>
316 <a target="_blank" href="Board/board.html#SpdData">Board</a> support<br>
317 </td>
318 <td>Select the following Kconfig values
319 <ul>
320 <li>DISPLAY_HOBS</li>
321 <li>DISPLAY_UPD_DATA</li>
322 </ul>
323 Testing successful if:
324 <ul>
325 <li>MemoryInit UPD values are correct</li>
326 <li>MemoryInit returns 0 (success) and</li>
327 <li>The the message "ERROR - coreboot's requirements not met by FSP binary!"
328 is not displayed
329 </li>
330 </ul>
331 </td>
332 </tr>
Lee Leahyde8c7e32016-02-14 14:55:29 -0800[diff] [blame]333 <tr>
Lee Leahybf08da22016-02-20 17:48:35 -0800[diff] [blame]334 <td>TempRamExit</td>
335 <td>src/drivers/intel/fsp1_1/<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l51">after_raminit.S</a></td>
336 <td>Post code 0x91
337 (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l212">POST_FSP_TEMP_RAM_EXIT</a>)
338 is displayed before calling TempRamExit by
339 <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l141">after_raminit.S</a>,
340 CONFIG_DISPLAY_MTRRS=y displays the correct memory regions and
341 Post code 0x39 is displayed by
342 <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l141">after_raminit.S</a><br>
343 </td>
344 </tr>
345 <tr>
Lee Leahyde8c7e32016-02-14 14:55:29 -0800[diff] [blame]346 <td>SiliconInit</td>
347 <td>
348 Implement the .init routine for the
349 <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a> structure
350 </td>
351 <td>During BS_DEV_INIT_CHIPS state, SiliconInit gets called and returns 0x00000000</td>
352 </tr>
353 <tr>
354 <td>FspNotify</td>
355 <td>
356 The code which calls FspNotify is located in
357 src/drivers/intel/fsp1_1/<a target="_blank" href="http://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/fsp_util.c;hb=HEAD#l182">fsp_util.c</a>.
358 The fsp_notify_boot_state_callback routine is called three times as specified
359 by the BOOT_STATE_INIT_ENTRY macros below the routine.
360 </td>
361 <td>
362 The FspNotify routines are called during:
363 <ul>
364 <li>BS_DEV_RESOURCES - on exit</li>
365 <li>BS_PAYLOAD_LOAD - on exit</li>
366 <li>BS_OS_RESUME - on entry (S3 resume)</li>
367 </ul>
368 </td>
369 </tr>
Lee Leahy7e0078b2016-01-31 11:48:15 -0800[diff] [blame]370</table>
371
372
373
Lee Leahyc1e4f892016-01-07 11:24:24 -0800[diff] [blame]374<hr>
Lee Leahye9a6d1a2016-01-31 11:28:06 -0800[diff] [blame]375<p>Modified: 4 March 2016</p>
Lee Leahyc1e4f892016-01-07 11:24:24 -0800[diff] [blame]376 </body>
377</html>