Notes about Vinum sources ------------------------- $Date: 2004/01/27 02:07:29 $ The Vinum master sources are currently split into two directories, one for the userland component and one for the kernel part. They reflect the FreeBSD implementation, but have deviated somewhat: the FreeBSD implementation is kept in the FreeBSD source tree, and from time to time I synchronize the master sources. The sources contain hundreds of ugly #ifdefs. The ones relating to operating systems are: BSD BSD-like system. Set for FreeBSD, NetBSD, OpenBSD FREEBSD Any FreeBSD system FREEBSD3 FreeBSD version 3 FREEBSD4 FreeBSD version 4 FREEBSD45 FreeBSD version 4 or 5 FREEBSD5 FreeBSD version 5 LINUX Any Linux system LINUX2_4 Linux 2.4 kernel LINUX2_5 Linux 2.5 kernel NETBSD Any NetBSD system The individual sources for each operating system are then built by targets in the Makefile, which is very tied to my personal system layout. See the targets f3, f4 and f5 for the corresponding release of FreeBSD, n5 and n6 for NetBSD 1.5 and 1.6, and l2.4 for Linux version 2.4. There's a job for somebody there just untangling the mess. Currently there's nothing for OpenBSD, but I'd expect it to be quite close to NetBSD. Don't get the impression that this means anything for Linux. The sources currently don't even compile. They're just a (sometimes not very good) best bet at how to start. The intention is to feed the fixes back into the master sources as they become functional. The master file contains a whole lot of ugly ifdef'd source intended to be passed through unifdef(1) in order to generate a legible version for individual operating systems. You shouldn't need to use it except for reference. Currently the Linux structure is all wrong; the files will need to be moved elsewhere, but I don't have a good idea where to put the userland sources for Linux. In more detail, the archive contains: sbin/ Userland commands. In BSDs, they would go in the hierarchy /usr/src/sbin/vinum. sbin/commands.c sbin/vext.h sbin/list.c sbin/v.c sbin/Makefile sys/dev/vinum/ Kernel module. In BSDs, they would go in the hierarchy /usr/src/sys/dev/vinum. sys/.gdbinit sys/vinum.c sys/makestatetext Script to make statexts.h sys/makeuser Script to create user header file. I'm not sure I use this any more. sys/vinumutil.h Header file used both in userland and kernel. sys/vinumobj.h Definitions of Vinum objects. This is a bit of a work in progress. I'm trying to find a way of defining the objects both in kernel and in userland, but without making kernel-only components visible in userland. I'd be interested in any input on this topic. sys/vinumvar.h Main header file. sys/vinumstate.h Definitions of object states. sys/vinumkw.h Keywords used both in kernel and userland. sys/vinumio.h ioctl definitions. sys/vinumext.h External definitions sys/request.h Request definitions. sys/vinumhdr.h More headers. sys/vinumdaemon.c The daemon code. The daemon is usually inactive. It performs I/O recovery and configuration saves. I'd guess it will compile relatively easily. sys/vinuminterrupt.c Interrupt-level code. complete_rqe is the iodone function. The big part of this is RAID-5 writes. The initial RAID-5 write request performs a read of the before images on disk. The reads complete and call complete_raid5_write in interrupt context. This is where the parity calculations and subsequent "real" writes take place. sys/vinumioctl.c ioctl routine. Also handles moving objects around. sys/vinumrevive.c Rebuild RAID volume routines, and check and rebuild RAID-[45] parity. sys/vinumlock.c Lock routines. You may have to do something quite different here. sys/vinumrequest.c This is the main entry point of the driver (vinumstrategy, vinumstart). It should be relatively easy to compile. For each request, Vinum creates a request block (defined in request.h). Basically it consists of a header and a number of request groups, one per plex in the volume. The request groups contain request elements, one per disk involved in the transfer. The whole mess gets handed to launch_requests(), in this file, which launches all requests in parallel in a double loop, though there's provision for throttling. brw() builds a request element, and build_read_request and build_write_request build request blocks. sys/vinumraid5.c This is the RAID-5 code, split out from vinumrequest.c because of its size. bre5() is the code which would belong in bre(), but it's 500 lines long by itself (including copious comments). sys/vinummemory.c Memory allocation routines for debug purposes. Effectively a no-op if VINUDEBUG isn't defined. sys/vinumstate.c State transition management. Here be dragons. If I ever get some time, I'll rework a lot of this. sys/vinumutil.c Utility routines. These should compile almost out of the box. sys/vinumio.c Low-level I/O stuff. This file will probably need an almost complete rewrite for Linux. It's not used for normal requests: it handles things like drive opens, location of Vinum partitions and saving the config. It's changing a lot at the moment. For example, the FreeBSD versions now support the root file system, but they're pretty dependent on FreeBSD features, so I haven't included them here. Hopefully it will be usable for BSD. The open_drive() in the NetBSD attempts is very old, from FreeBSD 2.2. Since then, it has been through some horrible hacks to try to guess what the drive is based on the device name, in oder to find the root file system before /dev was mounted. It's been fixed in a different way now, but I don't think it will apply to NetBSD. The fix is currently not in the master sources (I didn't do it). driveio() does low level I/O for config and such things. It's not used for normal data transfer. format_config is used to write config data back to the drives on status change. The driver calls save_config, which causes the daemon to perform the transfer in daemon_save_config. The volume label stuff is mainly for compatibility. You could leave it out first time round, though it shouldn't pose much of a porting problem. vinum_scandisk locates vinum partitions and reads in the configuration. In this form, it takes a list supplied by userland, which gets it from the devstat interface. I expect that NetBSD has a better way of doing things, since RAIDframe can mount the root file system. I can put the current FreeBSD code up in the master files, but it's not there yet. sys/vinumconfig.c Configuration routines. These read in the configuration, either from the user or from the data supplied by vinum_scandisk(), and create the in-kernel representation of the Vinum objects. sys/vinumparser.c Primitive keyword parser, used both in userland and kernel. It should compile OK, but if you come up with something better (not difficult), I'd take it back into the mainstream. This shouldn't be much of a challenge to port to other systems. sys/statetexts.h Texts for the individual object states. Built from vinumstate.h with the makestatetexts script. doc/vinum.4 doc/vinum.8 Man pages. If you start work on this, please let me know how you get on. Don't spend too much time on any one problem; send me the output and I may have an idea.