extensive patches to enable the program to compile under Linux using the
GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). Although
GNU-EFI is less sophisticated than recent versions of TianoCore's toolkit,
-GNU-EFI is my preferred environment because I prefer working in Linux and
-because TianoCore's toolkit relies on obsolete versions of Microsoft's
-Visual C++, and I had trouble tracking that down. For this reason, I used
-Debian's patched version of rEFIt as a starting point in forking rEFInd.
-The main down side to doing this is that a few rEFIt features got lost.
-Most notable among these is the ability to load filesystem drivers. I've
-also dropped ancillary programs, such as the ext2fs driver module and
+GNU-EFI is my preferred environment because versions of TianoCore that can
+build under Linux use a very different set of include files and support a
+somewhat different set of system calls than are used by rEFIt/rEFInd. Thus,
+converting to a new TianoCore toolkit would entail a lot of work. Using an
+older version would require building under Windows and using old versions
+of Microsoft's Visual C. I neither have this toolchain nor do I want to use
+it. For this reason, I used Debian's patched version of rEFIt as a starting
+point in forking rEFInd.
+
+I've dropped ancillary programs, such as the ext2fs driver module and
gptsync program, from rEFInd. You can still use these tools with rEFInd,
-but you'll need to install them separately; and in the case of filesystem
-drivers, you'll need to configure your EFI to load them before you launch
-rEFInd.
+but you'll need to install them separately.
+
+The patched version of rEFIt that I used as a starting point disabled the
+program's ability to load EFI drivers because of limitations in the GNU-EFI
+library. A combination of improvements in recent versions of the library
+and implementing a (now apparently abandoned) EFI function directly in
+rEFInd has enabled me to add this support back to rEFInd 0.2.7 and later.
Requirements
* A standard set of Linux development tools, based on GCC.
* The GNU-EFI package (http://sourceforge.net/projects/gnu-efi/). You
- can usually install this from a package called "gnu-efi".
+ can install this from a package called "gnu-efi"; however, rEFInd relies
+ on features that were added somewhere between GNU-EFI 3.0i and 3.0p to
+ provide driver-loading capabilities. As of 4/2012, most Linux
+ distributions seem to deliver rather elderly versions of GNU-EFI, so you
+ may need to download the latest source code, compile it, and install it
+ locally. Since rEFInd version 0.2.7, the Makefiles assume this (see
+ below).
It's possible that you could use a non-Linux platform to compile rEFInd. To
the best of my knowledge, the rEFInd code doesn't rely on anything
If rEFInd doesn't compile correctly, you'll need to track down the source
of the problem. Double-check that you've got all the necessary development
tools installed, including GCC, make, and GNU-EFI. You may also need to
-adjust the Makefile or Make.common file for your system. For instance, on
-Fedora, you must change the following variables in Make.common as shown:
-
-GNUEFILIB = /usr/lib64
-EFILIB = /usr/lib64
-EFICRT0 = /usr/lib64/gnuefi
+adjust the Makefile or Make.common file for your system. The most likely
+thing you'll need to change is the path to the various GNU-EFI include
+files and libraries. Since rEFInd 0.2.7, the default Make.common file
+includes the following definitions:
+
+EFIINC = /usr/local/include/efi
+GNUEFILIB = /usr/local/lib
+EFILIB = /usr/local/lib
+EFICRT0 = /usr/local/lib
+
+If you've installed GNU-EFI from a distribution's package, you may need to
+remove "local" from those paths, and perhaps change references to "lib" to
+"lib64". As noted earlier, though, as of 4/2012, most distributions provide
+out-of-date GNU-EFI implementations that will not work with rEFInd 0.2.7
+and later.
Installing rEFInd
-0.2.7 (?/??/2012):
+0.2.7 (4/19/2012):
------------------
- After much trial and tribulation, I've overcome a GNU-EFI limitation and
"scan_driver_dirs" entry to refind.conf to tell rEFInd where to look. (As
always, you should specify the driver directory relative to the root of
the filesystem.) Note that you can't launch drivers from another
- filesystem; they must be on the same volume that holds rEFInd.
+ filesystem; they must be on the same volume that holds rEFInd. Those who
+ compile from source code should note that implementing this feature
+ necessitated using a more recent version of the GNU-EFI library. I'm
+ currently using version 3.0p, and version 3.0i does NOT work. I don't
+ know where the change occurred, but you may need to upgrade your GNU-EFI
+ installation.
- Fixed bug that caused rEFInd to show up in its own menu sometimes.
https://sourceforge.net/projects/refind/. Consult the BUILDING.txt file in
the source code package for build instructions. Once you've built the
source code, you should duplicate the directory tree described above by
-copying the individual files and the icons directory to the ESP.
+copying the individual files and the icons directory to the ESP. Note that
+the binary file created by the build process will be called "refind.efi".
+You can use that name or rename it to include your architecture code, as
+you see fit.
<tr>
<td><tt>scan_driver_dirs</tt></td>
<td>directory path(s)</td>
- <td>Scans the specified directory or directories for EFI driver files. If rEFInd discovers <tt>.efi</tt> files in those directories, they're loaded and activated as drivers.</td>
+ <td>Scans the specified directory or directories for EFI driver files. If rEFInd discovers <tt>.efi</tt> files in those directories, they're loaded and activated as drivers. This option sets directories to scan <i>in addition to</i> the <tt>drivers</tt> subdirectory of the rEFInd installation directory, which is always scanned, if present.</td>
</tr>
<tr>
<td><tt>scanfor</tt></td>
# Sample refind.conf file
timeout 5
banner custom.bmp
-scan_driver_dirs drivers,EFI/refind/drivers
+scan_driver_dirs drivers,EFI/tools/drivers
scanfor manual,external,optical
default_selection elilo
</pre>
-<p>This example sets a timeout of 5 seconds; loads a custom graphic file called <tt>custom.bmp</tt> from the directory in which <tt>refind.efi</tt> resides; scans the <tt>drivers</tt> and <tt>EFI/refind/drivers</tt> directories for EFI drivers; uses manual boot loader configuration but also scans for external EFI boot loaders and EFI boot loaders on optical discs; and sets the default boot loader to the first loader found that includes the string <tt>elilo</tt>. Of course, since this file specifies use of manual boot loader configuration, it's not complete; you'll need to add at least one OS stanza to be able to boot from anything but an external disk or optical drive, as described shortly.</p>
+<p>This example sets a timeout of 5 seconds; loads a custom graphic file called <tt>custom.bmp</tt> from the directory in which <tt>refind.efi</tt> resides; scans the <tt>drivers</tt> and <tt>EFI/tools/drivers</tt> directories for EFI drivers; uses manual boot loader configuration but also scans for external EFI boot loaders and EFI boot loaders on optical discs; and sets the default boot loader to the first loader found that includes the string <tt>elilo</tt>. Of course, since this file specifies use of manual boot loader configuration, it's not complete; you'll need to add at least one OS stanza to be able to boot from anything but an external disk or optical drive, as described shortly.</p>
<h2>Creating OS Stanzas</h2>
<p><a href="index.html">Go to the main rEFInd page</a></p>
-<p><a href="linux.html">Learn about how to adjust rEFInd's appearance</a></p>
+<p><a href="linux.html">Learn about how to use EFI drivers with rEFInd</a></p>
<p><a href="http://www.rodsbooks.com/">Return</a> to my main Web page.</p>
</body>
<li><a href="configfile.html">Configuring the Boot Manager</a>—For advanced users, information on customizing a rEFInd installation</li>
+<li><a href="drivers.html">Using EFI Drivers</a>—Why and how to have rEFInd launch EFI drivers</li>
+
<li><a href="themes.html">Theming rEFind</a>—Information on third-party themes for rEFInd</li>
<li><a href="linux.html">Options for Booting Linux</a>—Methods of booting Linux, particularly with the EFI stub loader (distribution maintainers should read this!)</li>
<p class="subhead">by Roderick W. Smith, <a
href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
-<p>Originally written: 3/19/2012; last Web page update: 4/14/2012, referencing rEFInd 0.2.6</p>
+<p>Originally written: 3/19/2012; last Web page update: 4/19/2012, referencing rEFInd 0.2.7</p>
<p>I'm a technical writer and consultant specializing in Linux technologies. This Web page is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!</p>
</ul>
+<p>Ordinarily, a kernel booted in this way must reside on the ESP, or at least on another FAT partition. On a Macintosh, though, you can use HFS+ to house your kernel files. In fact, that may be necessary; my Mac Mini hangs when I try to boot a Linux kernel via an EFI stub loader from the computer's ESP, but it works fine when booting from an HFS+ partition. If you use <a href="drivers.html">EFI drivers,</a> though, you can place your kernel on any filesystem for which an EFI driver exists. This list is currently rather limited (ext2fs/ext3fs, ReiserFS, ISO-9660, and HFS+), but even just one or two options might help a lot if you've got an undersized ESP or if copying your kernel file to the ESP is a hassle you'd rather avoid.</p>
+
<p class="sidebar"><b>Tip for distribution maintainers:</b> If you maintain an <tt>EFI/<tt class="variable">distname</tt></tt> directory for your kernels, you can place your version of rEFInd in a directory called <tt>EFI/<tt class="variable">distname</tt>/refind</tt>. This will avoid collisions with duplicate rEFInd installations from other distributions.</p>
<p>On the whole, this method of configuration has a lot going for it. For distribution maintainers, if you place your Linux kernel files (with EFI stub support) on the ESP, with suitable filenames, matching initial RAM disk files, and a <tt>refind_linux.conf</tt> file, then any rEFInd 0.2.3 or later installation should detect your files, even if the user installs another distribution with another rEFInd that takes over from yours. (If the user, or this other rEFInd installation, disables auto-detection, this won't work.)</p>
<p class="subhead">by Roderick W. Smith, <a
href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
-<p>Last Web page update: 4/14/2012</p>
+<p>Last Web page update: 4/19/2012</p>
<p>I'm a technical writer and consultant specializing in Linux technologies. This Web page is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!</p>
<ul>
+<li><b>0.2.7 (4/19/2012)</b>—I've added two new tokens to the <tt>refind.conf</tt> file, with associated new functionality. The new <tt>scan_driver_dirs</tt> option tells rEFInd where to scan for EFI drivers, in addition to the default of the <tt>drivers</tt> subdirectory of the rEFInd installation directory. For more on EFI drivers, see <a href="drivers.html">Using EFI Drivers.</a> Note that previous versions of rEFInd couldn't load drivers at all, although they could make use of hardware and filesystems activated by drivers loaded before rEFInd launched. The second new token is <tt>also_scan_dirs</tt>, which adds arbitrary directories to the list that rEFInd scans for boot loaders. (Without this option, rEFInd scans each volume's boot directory and every subdirectory of the <tt>/EFI</tt> directory, with the exception of <tt>/EFI/tools</tt> and rEFInd's own directory.) This version also fixes a minor bug that caused rEFInd to sometimes include itself in the list of OS options. Finally, if you build rEFInd yourself, you should be aware that it now requires a newer version of the GNU-EFI library than it required in the past. See the <tt>BUILDING.txt</tt> file, included in the source code package, for details.</li>
+
<li><b>0.2.6 (4/14/2012)</b>—This version provides one bug fix and one new feature. The bug was introduced in version 0.2.5 and prevents rEFInd from identifying a Linux initial RAM disk file on some (but not all) EFI implementations. The new feature is the <tt>volume</tt> stanza token, which enables you to manually load a boot program from a filesystem other than the one from which rEFInd launched. You can specify a volume either by its label (as in <tt>volume KERNELS</tt> to load from the volume with a filesystem name <tt>KERNELS</tt>) or by number followed by a colon (as in <tt>volume 0:</tt> for the first filesystem or <tt>volume 1:</tt> for the second). See the <a href="configfile.html">Configuring the Boot Manager</a> page for more on this new feature.</li>
<li><b>0.2.5 (4/9/2012)</b>—Icon-handling improvements are key in this version. I've fixed a bug that caused icons to be replaced with ugly "not-found" default icons when rEFInd was launched in certain ways. I've also added support for <tt>.VolumeIcon.icns</tt> and <tt>.VolumeBadge.icns</tt> files to set loader tags and disk-type badges, respectively. (See the <a href="configfile.html">configuration page</a> for details.) I've also fixed a bug that prevented rEFInd from finding the correct initial RAM disk for Linux kernels stored in the root directory of a partition.</li>
<h2>Theming Basics</h2>
-<p></p>
+<p>As described on various other pages of this document, rEFInd relies on icon files located in its <tt>icons</tt> subdirectory, and occasionally elsewhere, to define its overall appearance. You can adjust rEFInd's theme in a few ways:</p>
+
+<ul>
+
+<li>You can create new icons and place them in the <tt>icons</tt> subdirectory. This will affect the appearance of the OS tags, the utility tags, and so on. The names of these icons are fairly self-explanatory. Be aware that rEFInd expects its icons to be in Apple's <a href="http://en.wikipedia.org/wiki/Icns">icon image format (ICNS).</a> You can generate such files easily in various Apple programs, or by using the <a href="http://icns.sourceforge.net/">libicns</a> library (and in particular its <tt>png2icns</tt> program) in Linux.</li>
+
+<li>You can customize the appearance of an individual boot loader by placing an ICNS file in its directory with the same name as the boot loader but with a <tt>.icns</tt> extension. For instance, if your boot loader program is <tt>elilo.efi</tt>, you can create a custom icon by naming it <tt>elilo.icns</tt>.</li>
+
+<li>You can provide an icon for boot loaders stored in the root directory of a filesystem by placing a file called <tt>.VolumeIcon.icns</tt> in that volume's root.</li>
+
+<li>You can set a custom badge (the small icon that identifies the disk type) by creating a file called <tt>.VolumeBadge.icns</tt> in that volume's root. This setting applies to all the boot loaders found on this volume, even if they're in subdirectories.</li>
+
+<li>You can adjust the selection background (used to highlight a selected icon) by creating new icons in Microsoft's <a href="http://en.wikipedia.org/wiki/BMP_file_format">BMP format</a>. You should create both 144x144 and 64x64 images and tell rEFInd about them by using the <tt>selection_big</tt> and <tt>selection_small</tt> tokens, respectively, in <tt>refind.conf</tt>.</li>
+
+<li>You can create a new background image and logo by placing a BMP file in rEFInd's main directory and passing its filename to rEFInd with the <tt>banner</tt> option in <tt>refind.conf</tt>. If the image is smaller than the screen, the color in the top-left corner of the image will be used for the rest of the display.</li>
+
+</ul>
+
+<p>Of course, not all of these elements are likely to be included in themes. A minimal rEFInd theme would include just some changes to the icons in the <tt>icons</tt> subdirectory. A more thorough theme would include a changed background image or selection backgrounds.</p>
+
+<p><b>Note:</b> If you'd like to design a logo for rEFInd, please do so! I lack the sort of artistic talent required for creating logos, so I just used plain text. I'd like to have something more eye-catching, though. I don't promise to use the first logo I'm given, but if you have some ideas, or would like to discuss some ideas, feel free to <a href="mailto:rodsmith@rodsbooks.com">e-mail me.</a></p>
<h2>Known Themes</h2>
-<p></p>
+<p>I used icons from the Oxygen Icons project, both from the <a href="http://deviantdark.deviantart.com/art/Oxygen-Refit-70199755">Oxygen Refit</a> package and from Gentoo's <tt>oxygen-icons</tt> package. These icons supplemented or replaced icons that rEFIt used; however, many OS icons (such as those for Windows and Mac OS) are carried over from rEFIt. I've also used a handful of icons for individual Linux distributions from other sources—usually documentation associated with the distribution in question.</p>
+
+<p>In addition to this default icon set, I've received word of one other rEFInd theme:</p>
+
+<ul>
+
+<li><a href="http://ecto-plazm.deviantart.com/art/rEFInd-Icon-Theme-296571397">ecto-plazm's theme</a></li>
+
+</ul>
+
+<p>If you've created or discovered another rEFInd theme, please <a href="mailto:rodsmith@rodsbooks.com">tell me about it</a> so that I can provide a link to it from this page.</p>
<hr />
<p class="subhead">by Roderick W. Smith, <a
href="mailto:rodsmith@rodsbooks.com">rodsmith@rodsbooks.com</a></p>
- <p>Originally written: 3/14/2012; last Web page update: 4/14/2012, referencing rEFInd 0.2.6</p>
+ <p>Originally written: 3/14/2012; last Web page update: 4/19/2012, referencing rEFInd 0.2.7</p>
<p>I'm a technical writer and consultant specializing in Linux technologies. This Web page is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!</p>
uses now (most of which come from the Oxygen Icons package), but I may
provide a way to make selecting a theme from one of several installed
themes easy, and provide links to themes on this Web site (or even host
-them on the project's Sourceforge page). Note that rEFInd currently
-supports only BMP format and ICNS format graphics files, and the former
-aren't very useful for icons because they lack transparency support. ICNS
-is an Apple format, and many Mac tools support it. In Linux, you can
-convert PNG images to ICNS format by using the <a
-href="http://icns.sourceforge.net/">libicns</a> library's <tt>png2icns</tt>
-program. I'm not sure what you'd use in Windows to create ICNS files.</li>
+them on the project's Sourceforge page). For more information on designing themes for rEFInd, see the <a href="themes.html">Theming rEFInd</a> page.</li>
<li>The code could be more flexible in its handling of the sizes of various graphical elements, and particularly drawn text. Prior to version 0.2.2, submenu text was invisible on UEFI-based PCs with 800x600 and smaller displays because of an inability to properly crop the graphics fields that hold the text. With version 0.2.2, I've put a band-aid on this problem by reducing the field size so that it now works on 800x600 displays, but smaller displays still suffer from this problem. This is just an example of the inflexibility of certain layout issues within rEFInd.</li>
<li>Although the ICNS file format used by rEFInd supports multiple image sizes, if a size that rEFInd needs isn't present in the file, rEFInd can't use the icon. The ability to scale images to the desired size would be useful.</li>
+<li>EFI supports network boots. rEFInd doesn't, but it would be nice if it would.</li>
+
<li>I would like to be able to specify the volume on which a boot loader resides using a partition GUID value, but extracting a GUID from the partition data is harder than extracting the volume's label or counting up the filesystem numbers.</li>
<li>It would be useful to be able to specify paths to boot loaders and/or initial RAM disks relative to the rEFInd directory (or the boot loader's directory, in the case of initrds).</li>
<li>There's currently no way to create a manual boot stanza for a BIOS-booted OS. This isn't a big priority for me personally, but I can see how it could be for some people.</li>
-<li>Returning from a program (such as an EFI shell or a boot loader that fails) produces an error message about a failure when "(re)opening our installation volume" on some computers. (Among mine, only a 32-bit Mac Mini produces this message.) This <i>seems to be</i> harmless, but I haven't removed the error message because I don't fully understand its cause or why it doesn't appear on most systems. This needs investigating and fixing.</li>
+<li>I'd like to find a way to get rEFInd to launch BIOS boot loaders on UEFI-based systems. This option currently works only on Macs—or at least, I've not gotten it to work on any of my UEFI-based PCs.</li>
+
+<li>Returning from a program (such as an EFI shell or a boot loader that fails) produces an error message about a failure when "(re)opening our installation volume" on some computers. (Among mine, only a 32-bit Mac Mini produces this message.) In some cases, rEFInd then hangs. I don't fully understand its cause or why it doesn't appear on most systems. This needs investigating and fixing.</li>
<li>The Page Up and Page Down keys work in a rather strange way—a result of an admittedly quick fix on my part to a problem with a data structure that makes implementation of scrolling harder than it ought to be.</li>
<li>A way to examine and change the NVRAM settings could be useful. This would enable a CD-based boot of rEFInd to fix a broken disk boot. Perhaps this could be done via a separate tool that could be launched much like the shell or <tt>gptsync</tt>.</li>
-<li>I'd like to find a way to get rEFInd to launch BIOS boot loaders on UEFI-based systems. This option currently works only on Macs—or at least, I've not gotten it to work on any of my UEFI-based PCs.</li>
-
<li>I'd like to find a way to have rEFInd re-scan removable media when they're inserted.</li>
<li>The code is in need of review to search for memory leaks and similar problems.</p>
# provide filesystem support, give access to hard disks on plug-in
# controllers, etc. In most cases none are needed, but if you add
# EFI drivers and you want rEFInd to automatically load them, you
-# should specify one or more paths here.
-# Default is to scan no directories for EFI drivers
+# should specify one or more paths here. rEFInd always scans the
+# "drivers" subdirectory of its own installation directory; this
+# option specifies ADDITIONAL directories to scan.
+# Default is to scan no additional directories for EFI drivers
#
-#scan_driver_dirs EFI/refind/drivers,drivers
+#scan_driver_dirs EFI/tools/drivers,drivers
# Which types of boot loaders to search, and in what order to display them:
# internal - internal EFI disk-based boot loaders
#include <efi/efi.h>
#include <efi/efilib.h>
-#ifndef _MY_SCAN_HANDLE_DATABASE
-#define _MY_SCAN_HANDLE_DATABASE
+#ifndef _DRIVER_SUPPORT
+#define _DRIVER_SUPPORT
// Below is from http://git.etherboot.org/?p=mirror/efi/shell/.git;a=commitdiff;h=b1b0c63423cac54dc964c2930e04aebb46a946ec;
// Seems to have been replaced by ParseHandleDatabaseByRelationshipWithType(), but the latter isn't working for me....
{
if (AboutMenu.EntryCount == 0) {
AboutMenu.TitleImage = BuiltinIcon(BUILTIN_ICON_FUNC_ABOUT);
- AddMenuInfoLine(&AboutMenu, L"rEFInd Version 0.2.6.2");
+ AddMenuInfoLine(&AboutMenu, L"rEFInd Version 0.2.7");
AddMenuInfoLine(&AboutMenu, L"");
AddMenuInfoLine(&AboutMenu, L"Copyright (c) 2006-2010 Christoph Pfisterer");
AddMenuInfoLine(&AboutMenu, L"Copyright (c) 2012 Roderick W. Smith");
CHAR16 *Directory;
UINTN i = 0, Length, NumFound = 0;
- // Scan user-specified driver directories....
+ // load drivers from the "drivers" subdirectory of rEFInd's home directory
+ Directory = StrDuplicate(SelfDirPath);
+ MergeStrings(&Directory, L"drivers", L'\\');
+// SPrint(DirName, 255, L"%s\\drivers", SelfDirPath);
+ NumFound += ScanDriverDir(Directory);
+
+ // Scan additional user-specified driver directories....
while ((Directory = FindCommaDelimited(GlobalConfig.DriverDirs, i++)) != NULL) {
Length = StrLen(Directory);
// Some EFI implementations won't read a directory if the path ends in