summaryrefslogtreecommitdiffstats
path: root/docs/install/index.html
blob: 56d50489bbdb29d9cbaf52a373f6d1a7157ddd5e (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
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1">

	<style type="text/css">
		@import url('../css/main.css');
	</style>

	<title>Installing libreboot</title>
</head>

<body>

	<div class="section">
		
		<h1 id="pagetop">Installing libreboot</h1>
			<p>
				This section relates to installing libreboot on supported targets.
			</p>
			<p>
				<a href="../index.html">Back to previous index</a>
			</p>
			
	</div>
			
	<div class="section">
			
		<h2>Software methods</h2>
			<ul>
				<li><a href="#rom">List of ROM images in libreboot</a></li>
				<li><a href="#flashrom">How to update or install libreboot (if you are already running libreboot or coreboot)</a></li>
				<li><a href="#flashrom">KFSN4-DRE: initial installation guide (if running the proprietary firmware)</a></li>
				<li><a href="#flashrom_lenovobios">ThinkPad X60/T60: Initial installation guide (if running the proprietary firmware)</a></li>
				<li><a href="#flashrom_macbook21">MacBook2,1: Initial installation guide (if running the proprietary firmware)</a></li>
			</ul>

		<h2>Hardware methods</h2>
			<ul>
				<li><a href="bbb_setup.html">How to program an SPI flash chip with the BeagleBone Black</a></li>
				<li><a href="bbb_ehci.html">How to configure EHCI debugging on the BeagleBone Black</a></li>
				<li><a href="x60_unbrick.html">ThinkPad X60: Recovery guide</a></li>
				<li><a href="x60tablet_unbrick.html">ThinkPad X60 Tablet: Recovery guide</a></li>
				<li><a href="t60_unbrick.html">ThinkPad T60: Recovery guide</a></li>
				<li><a href="x200_external.html">ThinkPad X200/X200S/X200T (needed if running the proprietary firmware, or to unbrick)</a></li>
				<li><a href="r400_external.html">ThinkPad R400 (needed if running the proprietary firmware, or to unbrick)</a></li>
				<li><a href="t400_external.html">ThinkPad T400 (needed if running the proprietary firmware, or to unbrick)</a></li>
				<li><a href="t500_external.html">ThinkPad T500 (needed if running the proprietary firmware, or to unbrick)</a></li>
			</ul>
			
	</div>

	<div class="section">

		<h1 id="rom">List of ROM images in libreboot</h1>

			<p>
				Libreboot distributes pre-compiled ROM images, built from the libreboot source code.
				These images are provided for user convenience, so that they don't have
				to build anything from source on their own.
			</p>

			<p>
				The ROM images in each archive use the following at the end of the file name,
				if they are built with the GRUB payload: <b>_<i>keymap</i>_<i>mode</i>.rom</b>
			</p>
			<p>
				Available <i>modes</i>: <b>vesafb</b> or <b>txtmode</b>. The <i>vesafb</i> ROM images are recommended, in most cases;
				<i>txtmode</i> ROM images come with MemTest86+, which requires text-mode instead of the usual framebuffer used
				by coreboot native graphics initialization.
			</p>
			<p>
				<i>keymap</i> can be one of several keymaps that keyboard supports (there are quite a few),
				which affects the keyboard layout configuration that is used in GRUB. It doesn't matter
				which ROM image you choose here, as far as the keymap in GNU/Linux is concerned.
			</p>
			<p>
				Keymaps are named appropriately according to each keyboard layout
				support in GRUB. To learn how these keymaps are created, see
				<a href="../grub/index.html#grub_keyboard">../grub/index.html#grub_keyboard</a>
			</p>
			
			<h2 id="qemu">QEMU</h2>
			
				<p>
					Libreboot comes with ROM images built for QEMU, by default:
				</p>

				<p>
					Examples of how to use libreboot ROM images in QEMU:
				</p>
					<ul>
						<li>$ <b>qemu-system-i386 -M q35 -m 512 -bios qemu_q35_ich9_keymap_mode.rom</b></li>
						<li>$ <b>qemu-system-i386 -M pc -m 512 -bios qemu_i440fx_piix4_keymap_mode.rom</b></li>
					</ul>
				<p>
					You can optionally specify the <b>-serial stdio</b> argument, so that QEMU will emulate
					a serial terminal on the standard input/output (most likely your terminal emulator or TTY).
				</p>
				<p>
					Other arguments are available for QEMU. The manual will contain more information.
				</p>

			<p>
				<a href="#pagetop">Back to top of page.</a>
			</p>
			
	</div>
	
	<div class="section">

		<h1 id="flashrom">How to update or install libreboot (if you are already running libreboot or coreboot)</h1>

			<p>
				On all current targets, updating libreboot can be accomplished without disassembly and,
				therefore, without having to externally re-flash using any dedicated hardware. In other words,
				you can do everything entirely in software, directly from the OS that is running on your libreboot
				system.
			</p>

			<div class="important">
				<p>
					<b>If you are using libreboot_src or git, then make sure that you built the sources first (see <a href="../git/index.html#build">../git/index.html#build</a>).</b>
				</p>
			</div>
			
			<p>
				Look at the <a href="#rom">list of ROM images</a> to see which image is compatible with your device.
			</p>

			<h2>Are you currently running the original, proprietary firmware?</h2>

				<p>
					If you are currently running the proprietary firmware (not libreboot or coreboot),
					then the flashing instructions for your system are going to be different.
				</p>
				<p>
					X60/T60 users running the proprietary firmware should refer to <a href="#flashrom_lenovobios">#flashrom_lenovobios</a>.
					MacBook2,1 users running Apple EFI should refer to <a href="#flashrom_macbook21">#flashrom_macbook21</a>
				</p>
				<p>
					X200 users, refer to <a href="x200_external.html">x200_external.html</a>,
					R400 users refer to <a href="r400_external.html">r400_external.html</a>,
					T400 users refer to <a href="t400_external.html">t400_external.html</a>,
					T500 users refer to <a href="t500_external.html">t500_external.html</a>
				</p>

			<h2>ASUS KFSN4-DRE?</h2>

				<p>
					Internal flashing should work just fine, even if you are
					currently booting the proprietary firmware.
				</p>

				<p>
					Libreboot currently lacks documentation for externally
					re-flashing an LPC flash chip. However, these boards have
					the flash chip inside of a PLCC socket, and it is possible
					to hot-swap the chips. If you want to back up your
					known-working image, simply hot-swap the chip for one that
					is the same capacity, after having dumped a copy of the
					current firmware (flashrom -p internal -r yourchosenname.rom),
					and then flash that chip with the known-working image.
					Check whether the system still boots, and if it does, then
					it should be safe to flash the new image (because you now
					have a backup of the old image).
				</p>

				<p>
					Keeping at least one spare LPC PLCC chip with working firmware
					on it is highly recommended, in case of bricks.
				</p>

				<p>
					<b>
						DO NOT hot-swap the chip with your bare hands. Use a PLCC
						chip extractor. These can be found online.
						See <a href="http://www.coreboot.org/Developer_Manual/Tools#Chip_removal_tools">http://www.coreboot.org/Developer_Manual/Tools#Chip_removal_tools</a>
					</b>
				</p>

				<p>
					Do check the HCL entry: <a href="../hcl/kfsn4-dre.html">../hcl/kfsn4-dre.html</a>
				</p>

			<h2>Are you currently running libreboot (or coreboot)?</h2>
				
				<p>
					X60/T60 users should be fine with this guide. If you write-protected the flash chip, please refer to 
					<a href="x60_unbrick.html">x60_unbrick.html</a>, <a href="x60tablet_unbrick.html">x60tablet_unbrick.html</a>
					or <a href="t60_unbrick.html">t60_unbrick.html</a>. <i>This probably does not apply to you. Most people
					do not write-protect the flash chip, so you probably didn't either.</i>
				</p>
				<p>
					Similarly, it is possible to write-protect the flash chip in coreboot or libreboot on GM45 laptops
					(X200/R400/T400/T500). If you did this, then you will need to use the links above for flashing, 
					treating your laptop as though it currently has the proprietary firmware (because write-protected SPI flash
					requires external re-flashing, as is also the case when running the proprietary firmware).
				</p>
				
				<p>
					If you did not write-protect the flash chip, or it came to you without any write-protection
					(<b><i>libreboot does not write-protect the flash chip by default, so this probably applies to you</i></b>),
					read on!
				</p>

			<h2>MAC address on GM45 (X200/R400/T400/T500)</h2>

				<p>
					<b>Users of the X200/R400/T400/T500 take note:</b> The MAC address for the onboard ethernet chipset
					is located inside the flash chip. Libreboot ROM images for these laptops contain a generic MAC
					address by default (00:F5:F0:40:71:FE), but this is not what you want.
					<i>Make sure to change the MAC address inside the ROM image, before flashing it.
					The instructions on <a href="../hcl/gm45_remove_me.html#ich9gen">../hcl/gm45_remove_me.html#ich9gen</a>
					show how to do this.</i>
				</p>

				<p>
					It is important that you change the default MAC address, before flashing. It will be printed on a sticker
					at the bottom of the laptop, or it will be printed on a sticker next to or underneath the RAM. Alternatively,
					and assuming that your current firmware has the correct MAC address in it, you can get it from your OS.
				</p>

			<h2>Flash chip size on GM45 (X200/R400/T400/T500)</h2>

				<p>
					Use this to find out:<br/>
					# <b>dmidecode | grep ROM\ Size</b>
				</p>

			<h2>All good?</h2>

				<p>Excellent! Moving on...</p>

				<p>
					Download the <i>libreboot_util.tar.xz</i> archive, and extract it. Inside, you will find
					a directory called <i>flashrom</i>. This contains statically compiled executable files of
					the <i>flashrom</i> utility, which you will use to re-flash your libreboot system.
				</p>

				<p>
					Simply use <i>cd</i> on your terminal, to switch to the <i>libreboot_util</i> directory. Inside,
					there is a script called <i>flash</i>, which will detect what CPU architecture you have
					(e.g. i686, x86_64) and use the appropriate executable. It is also possible for you to
					build these executables from the libreboot source code archives.
				</p>

				<div class="important">
					<p>
						How to update the flash chip contents:<br/>
						$ <b>sudo ./flash update <a href="#rom">yourrom.rom</a></b>
					</p>
				</div>
				<div class="important">
					<p>
						Ocassionally, coreboot changes the name of a given board. If flashrom complains about a board mismatch, but
						you are sure that you chose the correct ROM image, then run this alternative command:<br/>
						$ <b>sudo ./flash forceupdate <a href="#rom">yourrom.rom</a></b>
					</p>
				</div>

				<div class="important">

					<p>
						You should see <b>&quot;Verifying flash... VERIFIED.&quot;</b> written at the end of the flashrom output. <b>Shut down</b>
						after you see this, and then boot up again after a few seconds.
					</p>

				</div>

			<p><a href="#pagetop">Back to top of page</a></p>
			
	</div>

	<div class="section">

		<h1 id="flashrom_lenovobios">ThinkPad X60/T60: Initial installation guide (if running the proprietary firmware)</h1>

			<p><b>This is for the ThinkPad X60 and T60 while running Lenovo BIOS. If you already have coreboot or libreboot running,
			then go to <a href="#flashrom">#flashrom</a> instead!</b></p>

			<p><b>If you are flashing a Lenovo ThinkPad T60, be sure to read <a href="../hcl/index.html#supported_t60_list">../hcl/index.html#supported_t60_list</a></b></p>

			<div class="important">
				<p>
					<b>If you are using libreboot_src or git, then make sure that you built the sources first (see <a href="../git/index.html#build">../git/index.html#build</a>).</b>
				</p>
			</div>
			
			<p>
				<b>
					Warning: this guide will not instruct the user how to backup the original Lenovo BIOS firmware. These backups
					are tied to each system, and will not work on any other.
					For that, please refer to <a href="http://www.coreboot.org/Board:lenovo/x60/Installation">http://www.coreboot.org/Board:lenovo/x60/Installation</a>.
				</b>
			</p>

			<div class="important">

				<p>
					<b>
						If you're using libreboot 20150518, note that there is a mistake in the flashing script.
						Apply this patch to the BASH script named <i>flash</i> (this is the script for flashing
						libreboot into your X60): <a href="x60flashscript.patch">x60flashscript.patch</a>.
						This patch is merged in the main git repository, and in all releases after 20150518.
					</b>
				</p>
		
				<p>
					The first half of the procedure is as follows:<br/>
					$ <b>sudo ./flash i945lenovo_firstflash <a href="#rom">yourrom.rom</a>.</b>
				</p>
				
			</div>
			
			<div class="important">

				<p>
					You should see within the output the following:<br/>
					<b>&quot;Updated BUC.TS=1 - 64kb address ranges at 0xFFFE0000 and 0xFFFF0000 are swapped&quot;</b>.
				</p>

				<p>
					You should also see within the output the following:<br/>
					<b>&quot;Your flash chip is in an unknown state&quot;</b>, <b>&quot;FAILED&quot;</b> and <b>&quot;DO NOT REBOOT OR POWEROFF&quot;</b><br/>
					Seeing this means that the operation was a <b>resounding</b> success! <b>DON'T PANIC</b>.
				</p>

				<p>
					See this link for more details: 
					<a href="http://thread.gmane.org/gmane.linux.bios.flashrom/575">http://thread.gmane.org/gmane.linux.bios.flashrom/575</a>.
				</p>

				<p>
					If the above is what you see, then <b>SHUT DOWN</b>. Wait a few seconds, and then boot; libreboot is running, but there is a 2nd procedure <b>*needed*</b> (see below).
				</p>

			</div>

			<div class="important">
				<p>
					When you have booted up again, you must also do this:<br/>
					$ <b>sudo ./flash i945lenovo_secondflash <a href="#rom">yourrom.rom</a></b>
				</p>
				<p>
					If flashing fails at this stage, try the following:<br/>
					$ <b>sudo ./flashrom/i686/flashrom -p internal:laptop=force_I_want_a_brick -w <a href="#rom">yourrom.rom</a></b>
				</p>
			</div>

			<div class="important">

				<p>
					You should see within the output the following:<br/>
					<b>&quot;Updated BUC.TS=0 - 128kb address range 0xFFFE0000-0xFFFFFFFF is untranslated&quot;</b>
				</p>

				<p>
					You should also see within the output the following:<br/>
					<b>&quot;Verifying flash... VERIFIED.&quot;</b>
				</p>

			</div>

			<p><a href="#pagetop">Back to top of page.</a></p>
			
	</div>

	<div class="section">

		<h1 id="flashrom_macbook21">MacBook2,1: Initial installation guide (if running the proprietary firmware)</h1>

			<div class="important">

				<p>
					<b>If you have a MacBook1,1, refer to <a href="../hcl/index.html#macbook11">../hcl/index.html#macbook11</a> for flashing instructions.</b>
				</p>

			</div>

			<p>
				<b>
					This is for the MacBook2,1 while running Apple EFI firmware. If you already have 
					coreboot or libreboot running, then go to <a href="#flashrom">#flashrom</a> instead!
				</b>
			</p>

			<p>
				Be sure to read the information in <a href="../hcl/index.html#macbook21">../hcl/index.html#macbook21</a>.
			</p>
			
			<p>
				<b>
					Warning: this guide will not instruct the user how to backup the original Apple EFI firmware.
					For that, please refer to <a href="http://www.coreboot.org/Board:apple/macbook21">http://www.coreboot.org/Board:apple/macbook21</a>.
				</b>
			</p>

			<div class="important">
				<p>
					<b>If you are using libreboot_src or git, then make sure that you built the sources first (see <a href="../git/index.html#build">../git/index.html#build</a>).</b>
				</p>
			</div>

			<p>
				Look at the <a href="#rom">list of ROM images</a> to see which image is compatible with your device.
			</p>

			<div class="important">
				<p>
					Use this flashing script, to install libreboot:<br/>
					$ <b>sudo ./flash i945apple_firstflash <a href="#rom">yourrom.rom</a></b>
				</p>
			</div>

			<div class="important">

				<p>
					You should also see within the output the following:<br/>
					<b>&quot;Verifying flash... VERIFIED.&quot;</b>
				</p>

				<p>
					Shut down.
				</p>

			</div>

			<p><a href="#pagetop">Back to top of page.</a></p>
			
	</div>

	<div class="section">

		<p>
			Copyright &copy;  2014, 2015 Francis Rowe &lt;info@gluglug.org.uk&gt;<br/>
			Permission is granted to copy, distribute and/or modify this document
			under the terms of the GNU Free Documentation License, Version 1.3
			or any later version published by the Free Software Foundation;
			with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
			A copy of the license can be found at <a href="../gfdl-1.3.txt">../gfdl-1.3.txt</a>
		</p>

		<p>
			Updated versions of the license (when available) can be found at
			<a href="https://www.gnu.org/licenses/licenses.html">https://www.gnu.org/licenses/licenses.html</a>
		</p>

		<p>
			UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
			EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
			AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
			ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
			IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
			WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
			PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
			ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
			KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
			ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
		</p>
		<p>
			TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
			TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
			NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
			INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
			COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
			USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
			ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
			DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
			IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
		</p>
		<p>
			The disclaimer of warranties and limitation of liability provided
			above shall be interpreted in a manner that, to the extent
			possible, most closely approximates an absolute disclaimer and
			waiver of all liability.
		</p>
		
	</div>

</body>
</html>