ia64/xen-unstable

view tools/blktap/README @ 6946:e703abaf6e3d

Add behaviour to the remove methods to remove the transaction's path itself. This allows us to write Remove(path) to remove the specified path rather than having to slice the path ourselves.
author emellor@ewan
date Sun Sep 18 14:42:13 2005 +0100 (2005-09-18)
parents 0a4b76b6b5a0
children
line source
1 Block Tap User-level Interfaces
2 Andrew Warfield
3 andrew.warfield@cl.cam.ac.uk
4 February 8, 2005
6 NOTE #1: The blktap is _experimental_ code. It works for me. Your
7 mileage may vary. Don't use it for anything important. Please. ;)
9 NOTE #2: All of the interfaces here are likely to change. This is all
10 early code, and I am checking it in because others want to play with
11 it. If you use it for anything, please let me know!
13 Overview:
14 ---------
16 This directory contains a library and set of example applications for
17 the block tap device. The block tap hooks into the split block device
18 interfaces above Xen allowing them to be extended. This extension can
19 be done in userspace with the help of a library.
21 The tap can be installed either as an interposition domain in between
22 a frontend and backend driver pair, or as a terminating backend, in
23 which case it is responsible for serving all requests itself.
25 There are two reasons that you might want to use the tap,
26 corresponding to these configurations:
28 1. To examine or modify a stream of block requests while they are
29 in-flight (e.g. to encrypt data, or add data-driven watchpoints)
31 2. To prototype a new backend driver, serving requests from the tap
32 rather than passing them along to the XenLinux blkback driver.
33 (e.g. to forward block requests to a remote host)
36 Interface:
37 ----------
39 At the moment, the tap interface is similar in spirit to that of the
40 Linux netfilter. Requests are messages from a client (frontend)
41 domain to a disk (backend) domain. Responses are messages travelling
42 back, acknowledging the completion of a request. the library allows
43 chains of functions to be attached to these events. In addition,
44 hooks may be attached to handle control messages, which signify things
45 like connections from new domains.
47 At present the control messages especially expose a lot of the
48 underlying driver interfaces. This may change in the future in order
49 to simplify writing hooks.
51 Here are the public interfaces:
53 These allow hook functions to be chained:
55 void blktap_register_ctrl_hook(char *name, int (*ch)(control_msg_t *));
56 void blktap_register_request_hook(char *name, int (*rh)(blkif_request_t *));
57 void blktap_register_response_hook(char *name, int (*rh)(blkif_response_t *));
59 This allows a response to be injected, in the case where a request has
60 been removed using BLKTAP_STOLEN.
62 void blktap_inject_response(blkif_response_t *);
64 These let you add file descriptors and handlers to the main poll loop:
66 int blktap_attach_poll(int fd, short events, int (*func)(int));
67 void blktap_detach_poll(int fd);
69 This starts the main poll loop:
71 int blktap_listen(void);
73 Example:
74 --------
76 blkimage.c uses an image on the local file system to serve requests to
77 a domain. Here's what it looks like:
79 ---[blkimg.c]---
81 /* blkimg.c
82 *
83 * file-backed disk.
84 */
86 #include "blktaplib.h"
87 #include "blkimglib.h"
90 int main(int argc, char *argv[])
91 {
92 image_init();
94 blktap_register_ctrl_hook("image_control", image_control);
95 blktap_register_request_hook("image_request", image_request);
96 blktap_listen();
98 return 0;
99 }
101 ----------------
103 All of the real work is in blkimglib.c, but this illustrates the
104 actual tap interface well enough. image_control() will be called with
105 all control messages. image_request() handles requests. As it reads
106 from an on-disk image file, no requests are ever passed on to a
107 backend, and so there will be no responses to process -- so there is
108 nothing registered as a response hook.
110 Other examples:
111 ---------------
113 Here is a list of other examples in the directory:
115 Things that terminate a block request stream:
117 blkimg - Use a image file/device to serve requests
118 blkgnbd - Use a remote gnbd server to serve requests
119 blkaio - Use libaio... (DOES NOT WORK)
121 Things that don't:
123 blkdump - Print in-flight requests.
124 blkcow - Really inefficient copy-on-write disks using libdb to store
125 writes.
127 There are examples of plugging these things together, for instance
128 blkcowgnbd is a read-only gnbd device with copy-on-write to a local
129 file.
131 TODO:
132 -----
134 - Make session tracking work. At the moment these generally just handle a
135 single front-end client at a time.
137 - Integrate with Xend. Need to cleanly pass a image identifier in the connect
138 message.
140 - Make an asynchronous file-io terminator. The libaio attempt is
141 tragically stalled because mapped foreign pages make pfn_valid fail
142 (they are VM_IO), and so cannot be passed to aio as targets. A
143 better solution may be to tear the disk interfaces out of the real
144 backend and expose them somehow.
146 - Make CoW suck less.
148 - Do something more along the lines of dynamic linking for the
149 plugins, so thatthey don't all need a new main().