GGI Installation Guide
The GGI Project Team
$Date: 1998/02/17 10:51:27 $
This document describes how to install GGI. It covers patching the
Linux kernel, installing (Linux) kernel drivers and installing the
libggi.
1. Disclaimer
This software is still in its development stage. Make sure you read
ALL related documentation before attempting to install or use any
portion of GGI. For more information, see the GGI homepage
.
THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
2. Overview
First of all, thank you for trying GGI. The sources you obtained are
the GGI-0.0.9 public release. Not all of the drivers are in working
stage. However, they are included to have a broader testing base.
Please make sure you read all the README files related to the drivers,
there will be useful hints and notes about what works, what is known
not to work, how to fix problems etc.
To install GGI, the steps described in this document have to be done.
But you will not have to do these steps manually. There are scripts
(most of the time called 'configure') spread in the source tree that
will help you to configure and install GGI. This document will show
you what has to happen in order to install GGI to let you understand
what the scripts can do for you. Read 'README.configure' for more
information on the configuration scripts.
Basically you will:
o create, configure, build, install and boot a GGI-prepared kernel.
This is described in section ``Patching your kernel''
o configure, build and install drivers for your graphics cards. This
is described in section ``Installing the drivers''
o build and install ggilib-dynamic This is described in section
``Installing libggi''
o have fun running the demos without any root privileges This is not
described anywhere, as you know how to have fun, don't you ? But
before the fun, we have to do a little work.
3. Patching your Kernel
1. Extract this package.
Well you did already, so let's assume this file resides in the ggi-
v.e.r/ directory. If you obtained a development version of GGI,
from CVS or a snapshot page, the file will reside in the ggi/
directory.
2. Get a linux-2.x.x.tar.gz kernel archive of any 2.0 kernel or a
recent 2.1 kernel. Please look at the file ggi-
v.e.r/patches/Linux/Makefile for details and get a supported
kernel.
NOTE: Support for old 2.1 kernels may be dropped without notice if
maintaining four(!) kernel trees becomes too much work. Thank you
for your understanding.
3. Expand the linux source archive in /usr/src.
NOTE: The archive expands to linux/* so rename any directory or
link named "linux" before you extract the sources - otherwise your
current kernel source will be broken!
NOTE: You should also use a "fresh" kernel the first time, as these
are known to work well. If you have other patches applied, the GGI
patch may fail. Please check this before mailing a bug report.
4. We recommend you have a second kernel image to boot from either on
floppy or on harddisk. Don't rely on one image. See the man pages
or lilo docs for details. For example, save your current boot image
(e.g. /vmlinuz to /vmlinuz.sav), and add the following lines to
your /etc/lilo.conf file:
# rescue boot kernel
image = /vmlinuz.sav
root =
label = rescue_me
5. Go to the ggi-v.e.r/ directory and modify the kernel in
/usr/src/linux. Simply type
make patch_kernel KERNEL_VERSION=v.e.r
with v.e.r being the version of the kernel code in /usr/src/linux.
The Makefile will try to apply patches known to work, so don't
panic if it insists on using patches for a different kernel
version. It knows well about it's job, and you should trust it.
NOTE: The KERNEL_VERSION argument is optional, as the ggi-
v.e.r/patches/Linux/Makefile is able to extract it from the
kernel's Makefile.
NOTE: If the kernel source resides in a different directory than
the default one -- which is /usr/src/linux-- then specify its root
directory using the KERNELSRC option:
make patch_kernel KERNELSRC=/home/develop/linux-ggi
6. Now configure, compile, and install the new kernel. For instance,
you might want to do
cd /usr/src/linux; make config
and follow the instructions given there. Of course you will have to
substitute the directory path if your kernel resides in a different
directory than the default one.
Make sure you DO NOT enable the Magic SysRq patch as this will
break GGI/KGI!
If your keyboard is not supported, there is a patch to the kbd
utilities included (ggi-v.e.r/patches/utils/kbd-0.91.diff), so you
may create your own linux/drivers/char/i386/default/keymap.c file
using the patched loadkeys utility and your favorite keymap. If
you do so, make sure you map Graphic_nn keysyms to ALTGR-Fnn. See
the ibm-usa.kmap file for an example.
7. Now reboot and find as many bugs or features as possible.
NOTE: The current code expects all displays found to be in a
text16.80x25.80x25 mode. You might have to give the proper
arguments to the kernel if you normally like to boot e.g.
text16.132x43. This is because the kernel doesn't report the mode
of a second display when installed.
8. Create the device special files in /dev. To do this, run
make devices
from the ggi-v.e.r/ directory.
This will create the /dev/graph?? special files that are needed by
ggilib-dynamic.
9. Create the needed link in /usr/include. To do this, run
make install
This will create a link from /usr/include/ggi/ to ggi-
v.e.r/include/
The ggi-kernel should boot on any display your computer boots onto,
but only one VGA and/or only one MDA will be detected and served by
the boot driver. You can plug in both, and both should be detected.
If you see our boot logo flashing and get the system running, you have
done the first third of the installation procedure.
4. Installing the Drivers
You are still with us, so you have a GGI kernel running and you are
prepared for the next step. The new kernel has hooks to register input
and display drivers that are loaded as modules. You will have to
create the drivers first. To do this, please do the following steps:
1. Look at your graphics card and find out the hardware that's on it.
Especially you need to know:
o chipset manufacturer, chipset name/trademark/ID
o ramdac manufacturer, chip name/trademark/ID
o clock chip type and name/manufacturer/ID
o monitor type and parameters
If you don't know much about your card, but know it is a VGA
compatible device, try VGA settings. Use these too if your card is
not supported in "native" mode.
2. Change over to the ggi-v.e.r/driver directory.
3. If you did not patch the kernel from this source tree,
echo /where/the/linuxsrc/is > .kernelsrc
e.g.
echo /usr/src/linux-ggi > .kernelsrc
(This is normally done while patching the kernel.)
4. Run "make".
This will run the configure script first and let you do the
configuration by hand or automatically. You can also create a
config file with a normal editor, we suggest you create a normal
VGA config first and modify this one. See the README.CONFIG file
for more details.
After it, make will build dependencies and compile all the drivers
needed to create a driver as stated in ggi-v.e.r/driver/.config.
From now on, running "make" will rebuild this driver. If you want
to change the configuration, run "make config; make clean; make"
5. Run "make input"
This will compile all the configured input drivers.
6. Run (cd ../util ; make setmouse)
This will compile a setup utility foe the mouse which is used by
the insert script.
7. Insmod the new drivers. Normally
insert
does the job.
The new drivers will be located in the "modules" directory. The
toplevel "util" directory includes several programs to help you
tweak your mouse, mode settings, etc...
Please refer also to the corresponding files in the driver/.../.../
directories for possible options, known problems and other hints.
NOTE: With the 2.1 kernels, you need to upgrade your modutils to at
least version 2.1.34, otherwise module loading will not work.
Once the driver(s) are inserted, your system is - from the kernel side
- prepared so you can run the library and demos. Note that you will
have to insert the modules again after each boot. So a script to do
this is not a bad idea.
5. Installing libggi
1. Before attempting to install libggi, make sure you have met the
following requirements.
o linuxthreads-0.5 or higher (or glibc-2.0.2) is installed
o ld.so 1.7.14 or higher is installed
You may compile the ggilib-dynamic without multithread support, but
some features may be missing then.
2. Change over to the "lib/libggi" directory.
3. Run "make config"
This will bring up a configuration menu. You can choose whether you
want to use multithreading or not and you can select several
display targets, i.e. LibGGI can display in an X window or using
the kernel KGI driver for instance. Leave the menu with EXIT.
4. Run "make"
This will compile the library.
5. Run "make install" as root.
6. Now drop the root rights. You don't need them anymore.
7. "cd demos" and "make" there.
This will compile some demos.
Now you can try the demos available in the "demos" subdir. These will
show you some capabilities of libggi. Except for execution permission
and access permission to the /dev/graph?? files no other rights,
especially no SUID root is required.
If you can run the demos, you have successfully installed GGI, and now
you may play with it. You probably want to install XGGI, which can be
obtained from the ftp site
Have a lot of fun,
The GGI Project Team