Installation
In the example below the vesafb-tng frame buffer device is used.
Patching the Kernel
First make sure you have the fbsplash and vesafb-tng patches installed into your kernel. The sys-kernel/gentoo-sources version 2.6.8-r1 and higher should have these patches already installed. If you don't have these patches, you can get them from Spock's homepage (http://dev.gentoo.org/~spock/) and you can install them following the instructions on his page.
Configuring and Compiling the Kernel
Depending on whether you chose to use genkernel or compile the kernel manually, you will need to perform different steps in order to get support for fbsplash. Follow the appropriate section below.
Genkernel
Make sure /usr/src/linux points to your fbsplash patched kernel sources.
# ls -al /usr/src/linux
lrwxrwxrwx 1 root root 23 Jan 25 09:27 /usr/src/linux -> linux-2.6.something
If that's incorrect:
# rm /usr/src/linux
# ln -s /usr/src/linux-2.6-correct/ /usr/src/linux
Emerge the media-gfx/splashutils package, and configure your kernel and set gensplash to have genkernel add it to the initrd.
# emerge splashutils
# cd /usr/src/linux
# genkernel --menuconfig --gensplash=emergence all
If you wish to use an installed theme other than emergence, replace emergence in the above line with the theme name. Now, you must set the kernel options listed in the manual section below. Once you do that, you're all set. Genkernel will build and install your kernel with gensplash. Skip down to the configuring your bootloader.
Some users might have some trouble installing splashutils before configuring the kernel, if this is the case simply emerge splashutils after.
Manual Compilation
Change to the following directory and enter configuration:
# cd /usr/src/linux
# make menuconfig
First include the vesafb-tng frame buffer support in your kernel by choosing the options below. You can skip this step if you already configured a framebuffer driver besides vesa-tng.
| Code: make menuconfig |
Device Drivers > Graphics support: Device Drivers > Graphics support: |
If any of these options don't show up, make sure you didn't select tileblitting support:
Device Drivers > Graphics support:
[ ] Enable Tile Blitting Support
If you want to load the initramfs image dynamically at boot (you probably do), enable RAM disk support as well. (Genkernel users must select this option.)
Device Drivers > Block devices:
<*> RAM disk support
(4096) Default RAM disk size (kbytes) (NEW)
[*] Initial RAM disk (initrd) support
After you have configured your kernel, you must now compile it. WARNING: This step is essential before you install splashutils!
# make && make modules_install
Make sure /boot is mounted first, and then copy the files over. Please note that these filenames are not exact. You must name the /boot files depending on what kernel you are using. (For example, if I'm using gentoo-sources-2.6.11-r4, I would name the kernel, /boot/kernel-gentoo-2.6.11-r4. Also, do not worry about error messages on the mount /boot command. This is just a check to make sure your /boot partition is mounted.
# mount /boot
# cp arch/i386/boot/bzImage /boot/kernel-version
# cp System.map /boot/System.map-version
# cp .config /boot/config-version
Emerging splashutils
Now it's time to emerge media-gfx/splashutils. The splashutils package is a collection of binaries that are used to load the images into the framebuffer.
# emerge splashutils
Some users have encountered errors while attempting to build/emerge a 0.9.x(the current 'stable' version) ebuild of splashutils with kernel sources other than the officially supported gentoo-sources or gentoo-dev-sources. If this occurs, you may have success with one of the masked packages.
# echo ">=media-gfx/splashutils-1.1" >> /etc/portage/package.unmask
# echo "media-gfx/splashutils" >> /etc/portage/package.keywords
# emerge splashutils
This fix worked in a test case using ck-sources-2.6.11-ck3 and splashutils-1.1.9.3.
Making An initramfs Image
If you'd like to get your sexy background picture to appear earlier in your bootup process you'll have to use initramfs. Otherwise, you can skip to the section configuring your bootloader.
What is initramfs?
Initramfs (initial ramfs) is a chunk of code that unpacks the compressed cpio image midway through the kernel boot process. The files contained within that image are then used to populate the root filesystem. Initramfs is a part of a bigger concept called 'early-userspace' (Spock (http://dev.gentoo.org/~spock/)).
In order to use initramfs, an initramfs image has to be created. An initramfs image should contain:
- the pictures to be displayed as splash screen
- the necessary config files
- a userspace helper utility.
The pictures and config files (items 1 and 2) constitute a gensplash theme.
There are two ways of using the initramfs image. Either method works, however, it is recommended that you choose the second option because it is generally more convenient.
- compiling the initramfs image directly into the kernel
- loading the initramfs image dynamically at boot time
Compiling the Image Into the Kernel
First, delete the present initramfs image:
# rm -v /usr/src/linux/usr/initramfs_data.cpio.gz
Next, you'll have to create a new initramfs image containing the pictures, configs and the userspace helper. It is very easy using the utility splash_geninitramfs which was installed when you emerged splashutils.
# splash_geninitramfs -v -g /usr/src/linux/usr/initramfs_data.cpio.gz -r 1024x768 emergence
Compiling the initramfs image directly into the kernel has the disadvantage that you'll need to rebuild you kernel (that step is not required when using the second option - initrd):
# cd /usr/src/linux
# touch usr/initramfs_data.cpio.gz
# make bzImage
# mount /boot
# make install
Load Dynamically at Boot
In this option, you create the initramfs image as a stand-alone file, also known as the initrd file. Because of this, you will not have to recompile the kernel everytime you want to change the image. You will have to, however, specify an additional line in your boot loader config so that it knows it should load the initrd file.
So the only thing you have to do here is use splash_geninitramfs to generate an initrd file (that contains the pictures, configs and the userspace helper):
# mount /boot
# cd /etc/splash
# splash_geninitramfs -v -g /boot/fbsplash-emergence-1024x768 -r 1024x768 emergence
Change the resolution to match your monitor's resolution. For the purpose of this HOWTO, I'll stick with 1024x768.
However, quoting Spock (http://forums.gentoo.org/viewtopic.php?p=1488636#1488636), "you can't append initramfs data to an initrd image". Because of this, this option may not be used by the genkernel users since genkernel creates its own initrd image used during the boot process, unless you change kernel and initrd line in grub.conf from:
| File: /boot/grub/grub.conf |
root=/dev/ram0 real_root=/dev/$ROOT to root=/dev/$ROOT |
Obtain More Themes
The media-gfx/bootsplash-themes package has quite a lot of themes however it depends upon bootsplash. To emerge it while using gensplash the --nodeps and --oneshot options are needed to bypass the dependency and avoid trouble during emerge --update world:
# emerge --nodeps --oneshot bootsplash-themes
This will install the themes to /etc/bootsplash. You will then need to convert them to gensplash compatible themes.
Converting Bootsplash Themes to Gensplash Themes
Again, Spock has provided a handy utility called bootsplash2fbsplash which comes with splashutils to make converting bootsplash themes to the gensplash format easy. For example, if you have the bootsplash theme named gentoo-highquality located in /etc/bootsplash. All you have to do is issue the following command
# bootsplash2fbsplash gentoo-highquality
and the utility will create a gensplash-compatible theme inside the /etc/splash directory at /etc/splash/gentoo-highquality with all the required files.
Configuring Your Bootloader
Kernel Options
You first need an option which specifies the frame buffer device. In the following example, we specify that we would like to use vesafb-tng with ywrap and mttr support at a resolution of 1024x768, 16bpp color and a refresh rate of 85Hz.
video=vesafb:ywrap,mtrr,1024x768-16@85
Fbsplash requires its own option which allows you to specify which theme should be used. In this case, the default theme is emergence. The other option can be sent to verbose or silent. If silent is set, it will hide all the bootup information. Otherwise, you will be shown all the bootup information on system startup. Both these values have to be set.
splash=verbose,theme:emergence
If you decided to use an initrd file you will need to place an additional option in the boot loader config:
initrd /boot/fbsplash-emergence-1024x768 # Grub
initrd = /boot/fbsplash-emergence-1024x768 # Lilo
In the above example, it is assumed that the name of the initrd file is fbsplash-emergence-1024x768 (and it resides in the /boot partition or directory).
Below are examples for both Grub and Lilo config files. It is assumed that the custom theme 'newtheme', a resolution of 1280x1024, 32bpp and a refresh rate of 70Hz are used. The specified fbsplash mode is 'silent' and an initrd file is used (hence the additional 'initrd' line).
GRUB Example
| File: grub.conf |
title Gentoo Genkernel users should use something like this for the kernel line and the initrd line for the regular kernel: kernel (hd0,0)/boot/kernel-2.6.9-gentoo-r13 root=/dev/ram0 init=/linuxrc real_root=/dev/hda1 |
Replace (hd0,0) with your boot partition. If there is no separate boot partition, use the root partition number and prepend /boot to the kernel and initrd paths.
LILO Example
| File: lilo.conf |
image=/boot/kernel-2.6.8-gentoo-r1 |
Do not forget to run lilo after you have adjusted the lilo.conf file:
# mount /boot
# lilo -v
After all this work and a reboot you should have a graphical boot.
Adding Background To All Consoles
If you want all consoles to have a splash screen then type the following command:
# rc-update add splash default
Gensplash on Other Distributions
Gensplash will also work on other distributions. You can find tutorials for other distributions (Debian, Fedora and ArchLinux) at Spock's homepage (http://dev.gentoo.org/~spock/projects/gensplash/archive/contrib/).
Troubleshooting
Users With /usr on a Separate Partition
If you are using splashutils version 0.9-pre08 or later and have /usr on a separate partition, gensplash should work out of the box (without any modifications). If you, however, use an older version of splashutils and, for some bizarre reason, stubbornly refuse to update it, please use the instructions below.
The program and libraries that splash_util needs to run fbset and display your splash image are kept in /usr/bin and /usr/lib. So if you have these on separate partitions from / (such as a RAID or LVM2 partition), they may not be available (mounted) at the time splash_utils needs them (when using the older version of splashutils), and you won't see your beautiful splash.
The solution? Copy them to somewhere that they are available, as follows (with thanks to aslocum and the Gentoo forums Gensplash-How-to with progressbar!!!!! (http://forums.gentoo.org/viewtopic.php?t=206778&start=200&postdays=0&postorder=asc&highlight=) thread):
# cp /usr/bin/fbset /sbin
# cp /usr/lib/libjpeg.so.62 /lib
# cp /usr/lib/libpng.so.3 /lib
edit the /sbin/splash (nano works fine for this, just type nano -w /sbin/splash) and edit line 31 to read:
res=`/sbin/fbset | grep "^mode" | sed -r 's/mode "([0-9]+x[0-9]+).*/\1/'`
The only difference in this line is to add /sbin/ before fbset. Save and exit, and your splash should display properly.
I'm using an Intel i810 video device
I had alot of problems with vesa-tng working with an i810 integrated graphics controller. After hunting around the gentoo forums for a couple of days, I opted to use the i810fb instead. First, you need to reconfigure the kernel:
| Code: make menuconfig |
Device Drivers > Graphics support: |
Note that you should disable the VESA framebuffer and enable the i810 one. I did not have any luck having both running. Recompile the kernel and perform an install. I'm not sure if it is needed, but I emerge'd splashutils again and recreated my fbsplash files. Once this was done, the last tricky part is setting up the grub entry. In your kernel line, create the video entry as follows:
| File: grub.conf |
video=i810fb:vram:4,xres:1024,yres:768,bpp:16,hsync1:30,hsync2:55,vsync1:50,vsync2:85,accel |
Change your vram and sync settings as needed to support your adapter and/or monitor. These are fairly conservative and should work with most setups. Hopefully this helps.
I'm using an Radeon video device
I had kernel panics when suspending X11 due to vesafb-tng as shown below. My specific graphic card is ATI Technologies Inc Radeon Mobility M7 LW [Radeon Mobility 7500] running on an IBM T30
Oops: 0002 [#1]
PREEMPT
Modules linked in: vmnet parport_pc parport vmmon radeon drm intel_agp agpgart nvram usbcore
CPU: 0
EIP: 0060:[<b028c118>] Tainted: P VLI
EFLAGS: 00010292 (2.6.11-gentoo-r6)
EIP is at vesafb_do_vm86+0x38/0x3d0
eax: b0525720 ebx: 0000000 ecx: 0000000 edx: b0525720
esi: efbd9208 edi: b0525780 ebp: efbd9200 esp: efe3bed4
ds: 007b es: 007b ss: 0068
Process vesafb (pid: 18, threadinfo=efe3a000 task=dffef0a0)
Stack:
...
Call Trace
....
I used vesafb instead to solve this issue.
Background image loading in the middle of the boot process
You may (and probably will) find that the background image is loaded with a certain few-seconds-delay even when using an initramfs image. During that time the standard black-and-white 640x480 resolution is used.
Such behaviour is normal. The only workaround (in order to get the background image as early as possible) would be using the vesafb frame buffer device (instead of vesafb-tng). Here's Spock's elaborate answer (http://forums.gentoo.org/viewtopic.php?t=206778) on that issue: "The initramfs is used to populate the root filesystem before the frame-buffer subsystem is initialized, so it's good enough - don't worry about it. As you might have noticed, your PC boots into the text mode, and not the graphics mode. The graphics mode is set up when the framebuffer sub-system is initialized. But before that can happen, other things must be initialized, things that take some time. That's why for a second or two you might be seeing the kernel messages. You might say that with vesafb you didn't have those. And you will be right. But vesafb is an exception, not a rule (it's initialized while the kernel is being loaded) . Every other fb driver, including vesafb-tng, rivafb, radeonfb,... is initialized with the fbdev subsystem".
Compiling the initramfs image directly into the kernel rather than loading it at boot should also greatly reduce the time it takes to display the bootsplash image as it can then load all the necessery files straight away rather than waiting untill filesystems have been mounted.
I Use gentoo-ppc
To get fbsplash working on the PowerPC architecture, you need to add a line to your (possibly nonexistent) /etc/portage/package.keywords file:
media-gfx/splashutils ~ppc
This will tell emerge to ignore the fact that the splashutils package is unstable under ppc.
If you are using yaboot, then here is your initrd and append line (which go in your /etc/yaboot.conf file):
initrd=/boot/fbsplash-themename-resolution
append="video=radeonfb:resolution-bitdepth splash=silent"
The initrd should be relative to the root filesystem, but might be different based on your system setup. You might also place your initrd somewhere else entirely -- for instance, you could have my kernels in a /kernel directory and initrd images in /images.
putfont: PIO_FONT: Invalid argument
This message might appear in silent mode. To fix it, remove consolefont from the boot-runlevel:
rc-update del consolefont boot
It is safe to remove consolefont from the boot-runlevel, because fbsplash runs the setfont-command after finishing the boot anyway.
Contributors
Suggestions are welcome, if I've made some mistakes please correct them. I hope this How-To will help.
Greetings, RobDin
(Thanks, RobDin, it helped me, and I hope my small additions will help others too. --motub)
(Many modifications - especially (but not only) concerning the frame buffer devices - made by Jakub, I hope the author won't mind)
(Actually I have rewritten many parts of this howto. I'm afraid the original author might not like it but it's too late now. I'm sorry -- Jakub)
(@Jakub - I thought that making adaptions to How-To's is part of the gentoo-wiki way, feel free to make more adaptions. I allready knew that it was incomplete so I should thank you ;) -- RobDin)
(Me (fctk) heavyly modified this howto, too. I hope i didn't messed up something...)
(I made a modification to the lilo example, it had video=vesa instead of vesafb causing no image to load ;) --j79zlr)
(Thanks a ton RobDin, this helped me a bunch on my x86 laptop, and I liked it so much that I installed it on my PowerPC. I added a section to troubleshooting detailing the major changes I had to make to get this working on gentoo-ppc. I hope it works for other people too! ~Eko)
(Thanks RobDin this helped loads on my evo n160 however in silentmode the kernel text runs over the top of the image and pushes the image off screen :S LOL thanks again ~Cragdor)
(This helped alot. Added the putfont error. ~Rutto)
(Me (Tuvok), has made a small modification to the Genkernel section.)
Spanish Versión http://forums.gentoo.org/viewtopic.php?p=1606187