summaryrefslogtreecommitdiffstats
path: root/docs/index.html
blob: 720043e14c2176788cd681e05fc31169eaa9356e (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
<!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>Libreboot project documentation</title>
</head>

<body>
	
	<div class="section">
		<h1 id="pagetop">Libreboot project documentation</h1>
			<p>
				Information about this release can be found at <a href="release.html">release.html</a>.
				Always check <a href="http://libreboot.org">libreboot.org</a> for updates.
			</p>
			<p>
				<a href="#why">What is libreboot?</a>
			</p>
			<p>
				<a href="#version">How do I know what version I'm running?</a>
			</p>
	</div>
	
	<div class="section">
			
		<h1>Table of contents</h1>
			<ul>
				<li><a href="hcl/index.html">Hardware compatibility list</a> - <a href="https://www.gnu.org/distros/">GNU/Linux</a> is expected to be running on your device.</li>
				<li><a href="install/index.html">How to install libreboot</a></li>
				<li><a href="gnulinux/index.html">How to install GNU/Linux on a libreboot system</a></li>
				<li>
					<a href="git/index.html">How to use the git repository and build libreboot from source</a>
					<ul>
						<li><a href="maintain/index.html">Maintaining libreboot</a></li>
					</ul>
				</li>
				<li><a href="security/index.html">Hardware security</a></li>
				<li><a href="hardware/index.html">Hardware maintenance</a></li>
				<li><a href="grub/index.html">GRUB payload</a></li>
				<li><a href="misc/index.html">Miscellaneous</a></li>
			</ul>
			
	</div>

	<div class="section" id="why">

		<h1>About the libreboot project</h1>

			<p>
				Libreboot is a <a href="http://coreboot.org/">coreboot</a> distribution (distro) with proprietary software removed,
				intended to be a <a href="https://www.fsf.org/about/what-is-free-software">free</a>
				(libre) 'BIOS' replacement for your computer. The project is aimed at users, attempting to make
				coreboot as easy to use as possible. 
				Read the full <a href="https://www.gnu.org/philosophy/free-sw.html">Free Software definition</a>.
			</p>
			
			<p>
				Libreboot also has many practical advantages over <a href="https://gnu.org/philosophy/proprietary/">proprietary</a> boot firmware, 
				such as faster boot speeds and better security. You can
				<a href="gnulinux/index.html">install GNU/Linux with encrypted /boot/</a>,
				<a href="http://www.coreboot.org/GRUB2#signed_kernels">verify GPG signatures on your kernel</a>, 
				run a <a href="http://proteanos.com/">full operating system</a> directly
				from the flash chip (planned for a future release), and more.
			</p>

			<h2>
				The libreboot project has three main goals:
			</h2>
				<ul>
					<li>
						<i><u><b>Recommend and distribute only free software</b></u></i>.
						Coreboot distributes certain pieces of proprietary software which is needed on some systems.
						Examples can include things like CPU microcode updates, memory initialization blobs and so on.
						The coreboot project sometimes recommends adding more blobs which it does not distribute, such
						as the Video BIOS or Intel's <i>Management Engine</i>. However, a lot of dedicated and talented
						individuals in coreboot work hard to replace these blobs whenever possible.
					</li>
					<li>
						<i><u><b>Support as much hardware as possible!</b></u></i>
						Libreboot supports less hardware than coreboot, because most systems from coreboot still require
						certain proprietary software to work properly. Libreboot is an attempt to support as much
						hardware as possible, without any proprietary software.
					</li>
					<li>
						<i><u><b>Make coreboot easy to use</b></u></i>.
						Coreboot is notoriously difficult to install, due to an overall lack of user-focussed 
						documentation and support. Most people will simply give up before attempting to install coreboot.<br/><br/>
						
						Libreboot attempts to bridge this divide, making sure that everything from building
						to installing coreboot is automated, as much as is feasibly possible. Secondly, the project
						produces documentation aimed at non-technical users. Thirdly, the project attempts
						to provide excellent user support via mailing lists and IRC.<br/><br/>
						
						Libreboot already comes with a payload (GRUB), flashrom and other needed parts. Everything
						is fully integrated, in a way where most of the complicated steps that are otherwise required,
						are instead done for the user in advance.<br/><br/>
						
						You can download ROM images for your libreboot system and install them, without having
						to build anything from source. The build system is also fully automated, so building
						from source is easy if you wanted to do that (for whatever reason).
					</li>
				</ul>

			<h2>
				Libreboot is a coreboot distribution, not a coreboot fork
			</h2>

				<p>
					Libreboot is not a fork of coreboot. Every so often, the project re-based on the latest
					version of coreboot, with the number of custom patches in use minimized.
				</p>

				<p>
					All new coreboot development should be done in coreboot (upstream), not libreboot!
					Libreboot is about deblobbing and packaging coreboot in a user-friendly way, where most work
					is already done for the user.
				</p>
				
				<p>
					For example, if you wanted to add a new board to libreboot, you should add it to coreboot first.
					Libreboot will automatically receive your code at a later date, when it updates itself.
				</p>
				
				<p>
					The deblobbed coreboot tree used in libreboot is referred to as <i>coreboot-libre</i>,
					to distinguish it as a component of <i>libreboot</i>.
				</p>

			<h2>
				Libreboot is a 'stable' version of coreboot
			</h2>
				<ul>
					<li>
						Coreboot uses the <a href="https://en.wikipedia.org/wiki/Rolling_release">rolling release</a> model,
						which means that it is not guaranteed to be stable, or to even work at all on a given day.
						Coreboot does have a strict code review process, but being such a large project with so many contributors, regressions
						are always possible.
					</li>
					<li>
						Libreboot freezes on a particular revision of coreboot, making sure that everything works properly,
						making fixes on top of that and repeating this during each subsequent update to a later version
						of coreboot. By doing this, it provides a stronger guarantee to the user that the firmware
						will be reliable, and not break their system.
					</li>
				</ul>

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

	</div>

	<div class="section" id="version">

		<h1>How do I know what version I'm running?</h1>

			<p>
				If you are at least 127 commits after release 20150518
				(commit message <i>build/roms/helper: add version information to CBFS</i>)
				(or you have any <b>upstream</b> stable release of libreboot after 20150518), then you can
				press C at the GRUB console, and use this command to find out what version of libreboot you have:<br/>
				<b>cat (cbfsdisk)/lbversion</b><br/>
				This will also work on non-release images, built from the git repository.
				A file named <i>version</i> will also be included in the archives that you downloaded (if you are
				using release archives).
			</p>

			<p>
				If it exists, you can also extract this <i>lbversion</i> file by using the <i>cbfstool</i> utility
				which libreboot includes, from a ROM image that you either dumped or haven't flashed yet.
				In GNU/Linux, run cbfstool on your ROM image (<i>libreboot.rom</i>, in this example):<br/>
				$ <b>./cbfstool libreboot.rom extract -n lbversion -f lbversion</b><br/>
				You will now have a file, named <i>lbversion</i>, which you can read in whatever programme
				it is that you use for reading/writing text files.
			</p>

			<p>
				For git, it's easy. Just check the git log.
			</p>

			<p>
				For releases on or below 20150518, or snapshots generated from the git repository below 127 commits
				after 20150518, you can find a file named <i>commitid</i> inside the archives. If you are using
				pre-built ROM images from the libreboot project, you can press C in GRUB for access to the terminal,
				and then run this command:<br/>
				<b>lscoreboot</b><br/>
				You may find a date in here, detailing when that ROM image was built. For pre-built images distributed
				by the libreboot project, this is a rough approximation of what version you have, because the version
				numbers are dated, and the release archives are typically built on the same day as the release; you can
				correlate that with the release information in <a href="release.html">release.html</a>.
			</p>

			<p>
				You can also check the documentation that came with your archives, and in <i>docs/release.html</i> will be
				the information about the version of libreboot that you are using.
			</p>

			<p>
				Generally speaking, it is advisable to use the latest version of libreboot.
			</p>

	</div>

	<div class="section">
		
		<p>
			Copyright &copy; 2014, 2015 Francis Rowe &lt;info@gluglug.org.uk&gt;<br/>
			This document is released under the Creative Commons Attribution-ShareAlike 4.0 International Public License and all future versions.
			A copy of the license can be found at <a href="cc-by-sa-4.txt">cc-by-sa-4.txt</a>.
		</p>

		<p>
			This document is distributed in the hope that it will be useful,
			but WITHOUT ANY WARRANTY; without even the implied warranty of
			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See <a href="cc-by-sa-4.txt">cc-by-sa-4.txt</a> for more information.
		</p>
		
	</div>

</body>
</html>