[Xen-devel] [PATCH 03 of 13 v6] blktap3/libblktapctl: Introduce the tapdisk control header

[Thanos Makatos <thanos.makatos@xxxxxxxxxx>]

This patch introduces the header file where tapdisk control-related structures
and functions are declared. This file is based on the existing blktap2, with
most changes coming from blktap2.5.  Linux lists are replaced by BSD tail
queues. Few functions are partly documented, most of them are not documented at
all, this will be addressed by a future patch.

Signed-off-by: Thanos Makatos <thanos.makatos@xxxxxxxxxx>

---
Changed since v3:
  * Include file name and line number on log messages instead of function name.
  * Updated documentation for tap_ctl_create, tap_ctl_spawn.

Changed since v4:
  * Removed the minor number from struct tap_list.
  * Replaced the minor number with the /path/to/file or type:/path/to/file in
    all function declarations.
  * Moved here declarations of functions tap_ctl_connect_xenblkif and
    tap_ctl_disconnect_xenblkif.
  * Made function parse_params a public function.

Changed since v5:
  * Minor documentation improvements.

diff --git a/tools/blktap2/control/tap-ctl.h b/tools/blktap3/control/tap-ctl.h
copy from tools/blktap2/control/tap-ctl.h
copy to tools/blktap3/control/tap-ctl.h
--- a/tools/blktap2/control/tap-ctl.h
+++ b/tools/blktap3/control/tap-ctl.h
@@ -30,72 +30,261 @@
 
 #include <syslog.h>
 #include <errno.h>
+#include <sys/time.h>
+
+#include <inttypes.h>
+#include <xen/xen.h>
+#include <xen/grant_table.h>
+#include <xen/event_channel.h>
+
 #include <tapdisk-message.h>
+#include "blktap3.h"
 
+/*
+ * TODO These are private, move to an internal header.
+ */
 extern int tap_ctl_debug;
 
 #ifdef TAPCTL
-#define DBG(_f, _a...)                         \
-       do {                                    \
+#define DBG(_f, _a...)                 \
+       do {                                            \
                if (tap_ctl_debug)              \
                        printf(_f, ##_a);       \
        } while (0)
 
 #define DPRINTF(_f, _a...) syslog(LOG_INFO, _f, ##_a)
-#define EPRINTF(_f, _a...) syslog(LOG_ERR, "tap-err:%s: " _f, __func__, ##_a)
-#define  PERROR(_f, _a...) syslog(LOG_ERR, "tap-err:%s: " _f ": %s", __func__, 
##_a, \
-                                 strerror(errno))
+#define EPRINTF(_f, _a...) syslog(LOG_ERR, "tap-err:%s:%d " _f, __FILE__, \
+        __LINE__, ##_a)
+#define PERROR(_f, _a...) syslog(LOG_ERR, "tap-err:%s:%d " _f ": %s", \
+        __FILE__, __LINE__, ##_a, strerror(errno))
 #endif
 
-void tap_ctl_version(int *major, int *minor);
-int tap_ctl_kernel_version(int *major, int *minor);
+/**
+ * Contains information about a tapdisk process.
+ * TODO Or a VBD? If so, make it a union.
+ */
+typedef struct tap_list {
 
-int tap_ctl_check_blktap(const char **message);
-int tap_ctl_check_version(const char **message);
-int tap_ctl_check(const char **message);
+    /**
+     * The process ID.
+     */
+    pid_t pid;
 
+    /**
+     * State of the VBD, specified in drivers/tapdisk-vbd.h.
+     */
+    int state;
+
+    /**
+     * TODO
+     */
+    char *type;
+
+    /**
+     * /path/to/file
+     */
+    char *path;
+
+    /**
+     * for linked lists
+     */
+    TAILQ_ENTRY(tap_list) entry;
+} tap_list_t;
+
+TAILQ_HEAD(tqh_tap_list, tap_list);
+
+/**
+ * Iterate over a list of struct tap_list elements.
+ */
+#define tap_list_for_each_entry(_pos, _head) \
+    TAILQ_FOREACH(_pos, _head, entry)
+
+/**
+ * Iterate over a list of struct tap_list elements allowing deletions without
+ * having to restart the iteration.
+ */
+#define tap_list_for_each_entry_safe(_pos, _n, _head) \
+    TAILQ_FOREACH_SAFE(_pos, _head, entry, _n)
+
+/**
+ * Connects to a tapdisk.
+ *
+ * @param /path/to/file of the control socket (e.g.
+ * /var/run/blktap-control/ctl/<pid>
+ * @param socket output parameter that receives the connection
+ * @returns 0 on success, an error code otherwise
+ */
 int tap_ctl_connect(const char *path, int *socket);
-int tap_ctl_connect_id(int id, int *socket);
-int tap_ctl_read_message(int fd, tapdisk_message_t *message, int timeout);
-int tap_ctl_write_message(int fd, tapdisk_message_t *message, int timeout);
-int tap_ctl_send_and_receive(int fd, tapdisk_message_t *message, int timeout);
-int tap_ctl_connect_send_and_receive(int id,
-                                    tapdisk_message_t *message, int timeout);
+
+/**
+ * Connects to a tapdisk.
+ *
+ * @param id the process ID of the tapdisk to connect to
+ * @param socket output parameter that receives the connection
+ * @returns 0 on success, an error code otherwise
+ */
+int tap_ctl_connect_id(const int id, int *socket);
+
+/**
+ * Reads from the tapdisk connection to the buffer.
+ *
+ * @param fd the file descriptor of the socket to read from
+ * @param buf buffer that receives the output
+ * @param sz size, in bytes, of the buffer
+ * @param timeout (optional) specifies the maximum time to wait for reading
+ * @returns 0 on success, an error code otherwise
+ */
+int tap_ctl_read_raw(const int fd, void *buf, const size_t sz,
+        struct timeval *timeout);
+
+int tap_ctl_read_message(int fd, tapdisk_message_t * message,
+        struct timeval *timeout);
+
+int tap_ctl_write_message(int fd, tapdisk_message_t * message,
+        struct timeval *timeout);
+
+int tap_ctl_send_and_receive(int fd, tapdisk_message_t * message,
+        struct timeval *timeout);
+
+int tap_ctl_connect_send_and_receive(int id, tapdisk_message_t * message,
+        struct timeval *timeout);
+
 char *tap_ctl_socket_name(int id);
 
-typedef struct {
-       int         id;
-       pid_t       pid;
-       int         minor;
-       int         state;
-       char       *type;
-       char       *path;
-} tap_list_t;
+int tap_ctl_list_pid(pid_t pid, struct tqh_tap_list *list);
 
-int tap_ctl_get_driver_id(const char *handle);
+/**
+ * Retrieves a list of all tapdisks.
+ *
+ * @param list output parameter that receives the list of tapdisks
+ * @returns 0 on success, an error code otherwise
+ */
+int tap_ctl_list(struct tqh_tap_list *list);
 
-int tap_ctl_list(tap_list_t ***list);
-void tap_ctl_free_list(tap_list_t **list);
-int tap_ctl_find(const char *type, const char *path, tap_list_t *tap);
+/**
+ * Deallocates a list of struct tap_list.
+ *
+ * @param list the tapdisk information structure to deallocate.
+ */
+void tap_ctl_list_free(struct tqh_tap_list *list);
 
-int tap_ctl_allocate(int *minor, char **devname);
-int tap_ctl_free(const int minor);
+/**
+ * Creates a tapdisk process.
+ *
+ * TODO document parameters
+ * @param params type:/path/to/file
+ * @param flags
+ * @param prt_path parent /path/to/file (optional)
+ * @param secondary
+ * @returns 0 on success, an negative error code otherwise
+ */
+int tap_ctl_create(const char *params, int flags, const char * prt_path,
+        char *secondary);
 
-int tap_ctl_create(const char *params, char **devname);
-int tap_ctl_destroy(const int id, const int minor);
-
+/*
+ * TODO The following functions are not currently used by anything else
+ * other than the tapdisk itself. Move to a private header?
+ *
+ * @returns A positive integer on success, which the process ID of the tapdisk.
+ * Otherwise, a negative error code.
+ */
 int tap_ctl_spawn(void);
 pid_t tap_ctl_get_pid(const int id);
 
-int tap_ctl_attach(const int id, const int minor);
-int tap_ctl_detach(const int id, const int minor);
+/**
+ * @param pid the process ID of the tapdisk
+ * @param params type:/path/to/file
+ * @param prt_path parent /path/to/file (optional)
+ * @returns 0 on success, a (positive) error code otherwise
+ */
+int tap_ctl_open(const int pid, const char *params,
+        int flags, const char * prt_path, const char *secondary);
 
-int tap_ctl_open(const int id, const int minor, const char *params);
-int tap_ctl_close(const int id, const int minor, const int force);
+/**
+ * Closes the image.
+ *
+ * @param id the tapdisk process ID
+ * @param type:/path/to/file
+ */
+int tap_ctl_close(const int id, const char *params, const int force,
+        struct timeval *timeout);
+int tap_ctl_destroy(const int id, const char *params, int force,
+        struct timeval *timeout);
 
-int tap_ctl_pause(const int id, const int minor);
-int tap_ctl_unpause(const int id, const int minor, const char *params);
+/**
+ * Pauses the VBD.
+ */
+int tap_ctl_pause(const int id, const char * params, struct timeval
+        *timeout);
+/**
+ * Unpauses the VBD
+ */
+int tap_ctl_unpause(const int id, const char * params);
 
-int tap_ctl_blk_major(void);
+ssize_t tap_ctl_stats(pid_t pid, const char * params, char *buf, size_t size);
+int tap_ctl_stats_fwrite(pid_t pid, const char * params, FILE * out);
 
-#endif
+/**
+ * Retrieves virtual disk information from a tapdisk.
+ *
+ * @pid the process ID of the tapdisk process
+ * @params type:/path/to/file
+ * @sectors output parameter that receives the number of sectors
+ * @sector_size output parameter that receives the size of the sector
+ * @info TODO ?
+ *
+ */
+int tap_ctl_info(pid_t pid, const char *params, unsigned long long *sectors,
+        unsigned int *sector_size, unsigned int *info);
+
+/**
+ * Instructs a tapdisk to connect to the shared ring.
+ *
+ * @param pid the process ID of the tapdisk that should connect to the shared
+ * ring
+ * @param path /path/to/vdi
+ * @param domid the domain ID of the guest VM
+ * @param devid the device ID
+ * @param grefs the grant references
+ * @param order number of grant references, expressed as a 2's order
+ * @param port event channel port
+ * @param proto the protocol: native (XENIO_BLKIF_PROTO_NATIVE),
+ * x86 (XENIO_BLKIF_PROTO_X86_32), or x64 (XENIO_BLKIF_PROTO_X86_64)
+ * @param pool a string used as an identifier to group two or more VBDs
+ * beloning to the same tapdisk process. For VBDs with the same pool name, a
+ * single event channel is used.
+ * @returns 0 on success, a negative error code otherwise
+ */
+int
+tap_ctl_connect_xenblkif(const pid_t pid, const char *path,
+        const domid_t domid, const int devid, const grant_ref_t * grefs,
+        const int order, const evtchn_port_t port, int proto,
+        const char *pool);
+
+/**
+ * Instructs a tapdisk to disconnect from the shared ring.
+ *
+ * @param pid process ID of the tapdisk
+ * @param domid the ID of the guest VM
+ * @param devid the device ID of the virtual block device
+ * @param timeout timeout to wait, if NULL the function will wait indefinitely
+ * @returns 0 on success, a negative error code otherwise
+ */
+int
+tap_ctl_disconnect_xenblkif(const pid_t pid, const domid_t domid,
+        const int devid, struct timeval *timeout);
+
+/**
+ * Parses a type:/path/to/file string, storing the type and path to the output
+ * parameters. Upon successful completion the caller must free @type and @path,
+ * otherwise their values are undefined.
+ *
+ * @param params type:/path/to/file to parse
+ * @param type output parameter the receives the type
+ * @param path output paramter that receives the path
+ * @returns 0 on success
+ */
+int
+parse_params(const char *params, char **type, char **path);
+
+#endif /* __TAP_CTL_H__ */

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel