summaryrefslogtreecommitdiff
path: root/Documentation/Intel/development.html
blob: 24b2fa926103bd832c2ee8a5d39588e76ef04c10 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
<!DOCTYPE html>
<html>
  <head>
    <title>Development</title>
  </head>
  <body>

<h1>Intel&reg; x86 coreboot/FSP Development Process</h1>
<p>
  The x86 development process for coreboot is broken into the following components:
</p>
<ul>
  <li>coreboot <a target="_blank" href="SoC/soc.html">SoC</a> development</li>
  <li>coreboot <a target="_blank" href="Board/board.html">mainboard</a> development</li>
  <li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration</li>
</ul>
<p>
  The development process has two main phases:
</p>
<ol>
  <li>Minimal coreboot; This phase is single threaded</li>
  <li>Adding coreboot features</li>
</ol>

<h2>Minimal coreboot</h2>
<p>
  The combined steps below describe how to bring up a minimal coreboot for a
  system-on-a-chip (SoC) and a development board:
</p>
<table>
  <tr bgcolor="#ffffc0">
    <td>The initial coreboot steps are single threaded!
      The initial minimal FSP development is also single threaded.
      Progress can speed up by adding more developers after the minimal coreboot/FSP
      implementation reaches the payload.
    </td>
  </tr>
</table>
<ol>
  <li>Get the necessary tools:
    <ul>
      <li>Linux: Use your package manager to install m4 bison flex and the libcurses development
        package.
        <ul>
          <li>Ubuntu or other Linux distribution that use apt, run:
<pre><code>sudo apt-get install m4 bison flex libncurses5-dev
</code></pre>
          </li>
        </ul>
      </li>
    </ul>
  </li>
  <li>Build the cross tools for i386:
    <ul>
      <li>Linux:
<pre><code>make crossgcc-i386</code></pre>
        To use multiple processors for the toolchain build (which takes a long time), use:
<pre><code>make crossgcc-i386 CPUS=N</code></pre>
        where N is the number of cores to use for the build.
      </li>
    </ul>
  </li>
  <li>Get something to build:
    <ol type="A">
      <li><a target="_blank" href="fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li>
      <li><a target="_blank" href="SoC/soc.html#RequiredFiles">SoC</a> required files</li>
      <li><a target="_blank" href="Board/board.html#RequiredFiles">Board</a> required files</li>
    </ol>
  </li>
  <li>Get result to start <a target="_blank" href="SoC/soc.html#Descriptor">booting</a></li>
  <li><a target="_blank" href="SoC/soc.html#EarlyDebug">Early Debug</a></li>
  <li>Implement and debug the <a target="_blank" href="SoC/soc.html#Bootblock">bootblock</a> code</li>
  <li>Implement and debug the call to <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></li>
  <li>Enable the serial port
    <ol type="A">
      <li>Power on, enable and configure GPIOs for the
        <a target="_blank" href="Board/board.html#SerialOutput">debug serial UART</a>
      </li>
      <li>Add the <a target="_blank" href="SoC/soc.html#SerialOutput">serial outupt</a>
        support to romstage
      </li>
    </ol>
  </li>
  <li>Enable <a target="_blank" href="fsp1_1.html#corebootFspDebugging">coreboot/FSP</a> debugging</li>
  <li>Determine the <a target="_blank" href="SoC/soc.html#PreviousSleepState">Previous Sleep State</a></li>
  <li>Enable DRAM:
    <ol type="A">
      <li>Implement the SoC
        <a target="_blank" href="SoC/soc.html#MemoryInit">MemoryInit</a>
        Support
      </li>
      <li>Implement the board support to read the
        <a target="_blank" href="Board/board.html#SpdData">Memory Timing Data</a>
      </li>
    </ol>
  </li>
  <li>Disable the
    <a target="_blank" href="SoC/soc.html#DisableShadowRom">Shadow ROM</a>
  </li>
  <li>Enable CONFIG_DISPLAY_MTRRS to verify the MTRR configuration</li>
  <li>
    Implement the .init routine for the
    <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a>
    structure which calls FSP SiliconInit
  </li>
  <li>
    Start ramstage's
    <a target="_blank" href="SoC/soc.html#DeviceTree">device tree processing</a>
    to display the PCI vendor and device IDs
  </li>
  <li>
    Disable the
    <a target="_blank" href="Board/board.html#DisablePciDevices">PCI devices</a>
  </li>
  <li>
    Implement the
    <a target="_blank" href="SoC/soc.html#MemoryMap">memory map</a>
  </li>
  <li>coreboot should now attempt to load the payload</li>
</ol>



<h2>Add coreboot Features</h2>
<p>
  Most of the coreboot development gets done in this phase.  Implementation tasks in this
  phase are easily done in parallel.
</p>
<ul>
  <li>Payload and OS Features:
    <ul>
      <li><a target="_blank" href="SoC/soc.html#AcpiTables">ACPI Tables</a></li>
      <li><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</li>
    </ul>
  </li>
</ul>



<hr>
<table border="1">
  <tr bgcolor="#c0ffc0">
    <th colspan=3><h1>Features</h1></th>
  </tr>
  <tr bgcolor="#c0ffc0">
    <th>SoC</th>
    <th>Where</th>
    <th>Testing</th>
  </tr>
  <tr>
    <td>8254 Programmable Interval Timer</td>
    <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
    <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
  </tr>
  <tr>
    <td>8259 Programmable Interrupt Controller</td>
    <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
    <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
  </tr>
  <tr>
    <td>Cache-as-RAM</td>
    <td>
      <a target="_blank" href="SoC/soc.html#TempRamInit">Find</a>
      FSP binary:
      <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>
      Enable: FSP 1.1 <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a>
      called from
      <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>
      Disable: FSP 1.1 TempRamExit called from
      <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>
    </td>
    <td>FindFSP: POST code 0x90
      (<a target="_blank" href="https://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>)
      is displayed<br>
      Enable: POST code
      <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>
      is displayed<br>
      Disable: CONFIG_DISPLAY_MTRRS=y, MTRRs displayed after call to TempRamExit
    </td>
  </tr>
  <tr>
    <td>Memory Map</td>
    <td>
      Implement a device driver for the
      <a target="_blank" href="SoC/soc.html#MemoryMap">north cluster</a>
    </td>
    <td>coreboot displays the memory map correctly during the BS_WRITE_TABLES state</td>
  </tr>
  <tr>
    <td>MTRRs</td>
    <td>
      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>
      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>
    </td>
    <td>Set: Post code 0x91
      (<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>)
      is displayed by
      <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>
      Load: Post code 0x3C is displayed by
      <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>
      and CONFIG_DISPLAY_MTRRS=y displays the correct memory regions</td>
  </tr>
  <tr>
    <td>PCI Device Support</td>
    <td>Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a></td>
    <td>The device is detected by coreboot and usable by the payload</td>
  </tr>
  <tr>
    <td>Ramstage state machine</td>
    <td>
      Implement the chip and domain operations to start the
      <a target="_blank" href="SoC/soc.html#DeviceTree">device tree</a>
      processing
    </td>
    <td>
      During the BS_DEV_ENUMERATE state, ramstage now display the device IDs
      for the PCI devices on the bus.
    </td>
  </tr>
  <tr>
    <td>ROM Shadow<br>0x000E0000 - 0x000FFFFF</td>
    <td>
      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>
    </td>
    <td>Operates as RAM: Writes followed by a read to the 0x000E0000 - 0x000FFFFF region returns the value written</td>
  </tr>


  <tr bgcolor="#c0ffc0">
    <th>Board</th>
    <th>Where</th>
    <th>Testing</th>
  </tr>
  <tr>
    <td>Device Tree</td>
    <td>
      <a target="_blank" href="SoC/soc.html#DeviceTree">List</a> PCI vendor and device IDs by starting
      the device tree processing<br>
      <a target="_blank" href="Board/board.html#DisablePciDevices">Disable</a> PCI devices<br>
      Enable: Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a>
    <td>
      List: BS_DEV_ENUMERATE state displays PCI vendor and device IDs<br>
      Disable: BS_DEV_ENUMERATE state shows the devices as disabled<br>
      Enable: BS_DEV_ENUMERATE state shows the device as on and the device works for the payload
    </td>
  </tr>
  <tr>
    <td>DRAM</td>
    <td>
      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>
      UPD Setup:
      <ul>
        <li>src/soc&lt;Vendor&gt;//&lt;Chip Family&gt;/romstage/<a target="_blank" href="SoC/soc.html#MemoryInit">romstage.c</a></li>
        <li>src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/<a target="_blank" href="Board/board.html#SpdData">romstage.c</a></li>
      </ul>
      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>
    </td>
    <td>Select the following Kconfig values
      <ul>
        <li>DISPLAY_HOBS</li>
        <li>DISPLAY_UPD_DATA</li>
      </ul>
      Testing successful if:
      <ul>
        <li>MemoryInit UPD values are correct</li>
        <li>MemoryInit returns 0 (success) and</li>
        <li>The the message "ERROR - coreboot's requirements not met by FSP binary!"
          is not displayed
        </li>
      </ul>
    </td>
  </tr>
  <tr>
    <td>Serial Port</td>
    <td>
      SoC <a target="_blank" href="SoC/soc.html#SerialOutput">Support</a><br>
      Enable: src/soc/mainboard/&lt;Board&gt;/com_init.c/<a target="_blank" href="Board/board.html#SerialOutput">car_mainboard_pre_console_init</a>
    </td>
    <td>Debug serial output works</td>
  </tr>


  <tr bgcolor="#c0ffc0">
    <th>Payload</th>
    <th>Where</th>
    <th>Testing</th>
  </tr>
  <tr>
    <td>ACPI Tables</td>
    <td>
      SoC <a target="_blank" href="SoC/soc.html#AcpiTables">Support</a><br>
    </td>
    <td>Verified by payload or OS</td>
  </tr>


  <tr bgcolor="#c0ffc0">
    <th>FSP</th>
    <th>Where</th>
    <th>Testing</th>
  </tr>
  <tr>
    <td>TempRamInit</td>
    <td>FSP <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></td>
    <td>FSP binary found: POST code 0x90
      (<a target="_blank" href="https://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>)
      is displayed<br>
      TempRamInit successful: POST code
      <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>
      is displayed<br>
    </td>
  </tr>
  <tr>
    <td>MemoryInit</td>
    <td><a target="_blank" href="SoC/soc.html#MemoryInit">SoC</a> support<br>
      <a target="_blank" href="Board/board.html#SpdData">Board</a> support<br>
    </td>
    <td>Select the following Kconfig values
      <ul>
        <li>DISPLAY_HOBS</li>
        <li>DISPLAY_UPD_DATA</li>
      </ul>
      Testing successful if:
      <ul>
        <li>MemoryInit UPD values are correct</li>
        <li>MemoryInit returns 0 (success) and</li>
        <li>The the message "ERROR - coreboot's requirements not met by FSP binary!"
          is not displayed
        </li>
      </ul>
    </td>
  </tr>
  <tr>
    <td>TempRamExit</td>
    <td>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#l51">after_raminit.S</a></td>
    <td>Post code 0x91
      (<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>)
      is displayed before calling TempRamExit by
      <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>,
      CONFIG_DISPLAY_MTRRS=y displays the correct memory regions and
      Post code 0x39 is displayed by
      <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>
    </td>
  </tr>
  <tr>
    <td>SiliconInit</td>
    <td>
      Implement the .init routine for the
      <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a> structure
    </td>
    <td>During BS_DEV_INIT_CHIPS state, SiliconInit gets called and returns 0x00000000</td>
  </tr>
  <tr>
    <td>FspNotify</td>
    <td>
      The code which calls FspNotify is located in
      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/fsp_util.c;hb=HEAD#l182">fsp_util.c</a>.
      The fsp_notify_boot_state_callback routine is called three times as specified
      by the BOOT_STATE_INIT_ENTRY macros below the routine.
    </td>
    <td>
      The FspNotify routines are called during:
      <ul>
        <li>BS_DEV_RESOURCES - on exit</li>
        <li>BS_PAYLOAD_LOAD - on exit</li>
        <li>BS_OS_RESUME - on entry (S3 resume)</li>
      </ul>
    </td>
  </tr>
</table>



<hr>
<p>Modified: 4 March 2016</p>
  </body>
</html>