# $Id: README,v 1.4 2003/01/08 07:48:16 rogerb Exp $ # SKAS 3 as a module, 7 January 2002 # by Roger Binns This is Jeff Dike's UML kernel helper code known as SKAS. It is normally distributed as a kernel patch. This code provides it as a module instead. SKAS stands for Seperate Kernel Address Space and refers to a mode of operation for User Mode Linux that is significantly better performing than the default (tracing thread) method. It does however require that the kernel is patched. See http://user-mode-linux.sourceforge.net for more details. NOTE: The SKAS patch is distributed by Jeff as a kernel patch only at http://user-mode-linux.sourceforge.net/dl-sf.html (Scroll to the bottom) If you are able to build your own kernels, you are highly recommended to do so with the patch above. ========= !WARNING! ========= This module can be very dangerous if it is misconfigured or you attempt to bludgeon it into the kernel. In particular, it will only work against the kernel you compiled it for, and no other. It tries to verify that it is not being used against the wrong kernel, but that verification can't be perfect. Use it at your own risk. It breaks several rules that kernel modules are expected to comply with. Specifically: - it copies kernel code, and patches it with sed/awk - the code it copies deals with memory management and mapping which is where each vendor has their own fixes and "enhancements" - it modifies the system call table - it uses symbols that haven't been exported by the kernel, and gets their values from System.map at compile time RATIONALE This code solves the problem of building the SKAS code as a module. That means you won't have to recompile your kernel. This is extremely useful if you use vendor kernels such as Redhat since compiling their kernels to add the SKAS patch is extremely time consuming and not a lot of fun. COMPATABILITY This is known to work as is on 8.0 kernels. I believe it requires adding a few symbols to the syms file for Redhat 7.3. If you don't have those, then read the backgound and porting sections further below. REQUIREMENTS You need to have the kernel source available that was used for your current kernel. It is also extremely important that it is the exact source that was used for your kernel, not some random one with a similar version number. You also need the System.map file for the kernel. This lists what addresses symbols are at. It must also match your exactly kernel. Note that the System.map is different for each kernel compile. For example, it differs if the kernel was optimised for AMD Athlon versus the Pentium II series etc. Fortunately, most vendors provide the source as a 'kernel-source' RPM, and install the System.map alongside the kernel. They are even in sensible locations. For example, for the Redhat 8.0 kernel 2.4.18-18.8.0 (find the version using `uname -r'), the source is in /usr/src/linux-2.4.18-18.8.0 and the system map is /boot/System.map-2.4.18-18.8.0 BUILDING Just type make. The Makefile looks in the patterns listed above for the relevant source and map. You will end up with a file 'skas.o'. There should be no warnings or errors. IF THERE ARE ANY WARNINGS, DO NOT USE THE MODULE. RUNNING To turn SKAS on, as root run 'insmod skas.o'. You can remove it by running 'rmmod skas.o'. You can tell if it is running by looking for a file named /proc/mm. It will also show up in the output of 'lsmod' (look at the top). Note that you can't remove it while SKAS functionality is being used by a running UML. BACKGROUND The SKAS patch does 3 things. It changes 3 Linux kernel memory management functions. These functions are coded to work only on the process on the current CPU. SKAS changes them to work on any process' memory. It then adds some requests to the ptrace system call, and adds in a file /proc/mm that when you call it allows the creation and manipulation of memory regions. The new ptrace options, and /proc/mm stuff calls the memory management functions. This module code works by copying the relevant functions from the kernel source (which is why it needs the exact same source). It also modifies them to work on any memory map, and renames them so they can't be confused with the existing function. The /proc/mm code is virtually unchanged from the SKAS patch, except to use the new function names. A new ptrace system call is put into the system table. The new call checks the request to see if it is one of the new ones added. If so, it calls an SKAS ptrace that implements those. If not, it sends it through to the original ptrace call. One difficulty is that the kernel only exports some of the symbols needed by the above code. In order to get the rest, this code finds them in the System.map. The System.map gives the exact location of those symbols. This is why the correct System.map must be used. The module does make some attempt to detect that it is being inserted into the wrong kernel. In particular it compares what address the function sys_listen had in the System.map with what it is in the running kernel. If they differ, something has gone very wrong and it refuses to load. PORTING If you try to move this code to another kernel not listed earlier, it may fail to compile, or there may be some warning. In either case, if you are not a reasonably competent C programmer, please find one to help you that has the same kernel as you. If you get warnings about implicit declarations of functions in proc_mm.c, generally all you need to do is add prototypes. You should grep the kernel headers for the declaration and include the appropriate file. If you can't find the declaration in the kernel headers, then the function is normally in the same file as the function was extracted from. Note that proc_mm.c #includes several C files (each an extracted function from the kernel source). The C files are generated so do not edit them directly. Edit the shell script that generates them. This usually occurs for dommappgoff.c, so look in fixdommappgoff.sh. Look in the relevant kernel source file for the function. If the functions are 'static inline' then you need to use the exctractfunction stuff. Otherwise, add a prototype for them (exclude any 'static' though). Once everything compiles, the insmod command may say there are missing symbols. (Note that the insmod run by make just checks that the module could be loaded - it does not load it). For each of the missing symbols, add it to the 'syms' file. The result should work fine. I also hope you realise just how important it is that you have the correct kernel source and System.map. I take no responsibility for any death and destruction that may result.