Initial usbdump helper

USB packets are captured in the pcap format using the Linux usbmon
link-layer type. Right now, this only works with handle_ctrl. Data
packets (isochronous, bulk and interrupt) are not (fully)
implemented yet.

Signed-off-by: Peter Wu <peter@lekensteyn.nl>

1 files changed, 77 insertions, 0 deletions

diff --git a/hw/usb/dump.h b/hw/usb/dump.h
new file mode 100644
index 0000000000..1478fdc44c
--- /dev/null
+++ b/hw/usb/dump.h
@@ -0,0 +1,77 @@
+/*
+ * USB capture helper.
+ *
+ * Copyright (c) 2014 Peter Wu <peter@lekensteyn.nl>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+#ifndef QEMU_HW_USB_DUMP_H
+#define QEMU_HW_USB_DUMP_H
+
+#include "qapi-types.h"
+
+typedef struct UsbDumpState UsbDumpState;
+
+/*
+ * p->pid shows whether a packet is IN, OUT or SETUP.
+ *
+ * handle_ctrl is called for:
+ * - SETUP (setup dir IN): setup_buf provided, data ptr is data (setup_len > 0)
+ * - IN: setup_len > 0 (data): callback for OUT
+ * - (same code path: IN: setup_len == 0 (!data): Called iff dir is OUT
+ *   (otherwise BROKEN!))
+ * - Note: never called in OUT.
+ *
+ * Possible combinations (^X,Y = handle_ctrl called, X and Y are Submission or
+ * Callback where X is called before processing the data in handle_ctrl, and Y
+ * must be called right before returning because data is modified. If order does
+ * not matter (e.g. XY, then the order is still recommended to be X,Y for timing
+ * considerations)):
+ * - setup^S,C(setup_len > 0, IN) / data(IN) / status(OUT) - Submission contains
+ *   setup packet with no data (actual_length == 0), callback contains data (len
+ *   actual_length).
+ * - setup(setup_len > 0, OUT) / data(OUT) / status^SC,(IN) - Submission
+ *   contains setup packet and data (len setup_len), callback contains no data
+ *   (just success).
+ * - setup(setup_len == 0, IN) / status^SC,(IN) - Same as above (with
+ *   status(IN)), but there is no data for both submission and callback.
+ * - setup(setup_len == 0, OUT) / status(OUT) (BROKEN!)
+ */
+
+/*
+ * submit (ctrl): always log setup_buf, do not use PID for determining
+ * direction, but setup_buf[0]. data is empty for PID == SETUP; for PID == IN,
+ * data is of length setup_len. PID == OUT is not possible because handle_ctrl
+ * is never called from that point.
+ */
+void usb_dump_submit(UsbDumpState *s, USBPacket *p);
+/*
+ * complete (ctrl): setup_is irrelevant. If PID == SETUP, then the data was just
+ * inserted by the "device" in handle_ctrl. Length is actual_length. If PID ==
+ * IN, then data is empty. PID == OUT is again not possible (see submit).
+ */
+void usb_dump_complete(UsbDumpState *s, USBPacket *p);
+
+
+void usb_dump_cleanup(UsbDumpState *s);
+
+int usb_dump_init(UsbDumpState *s, const char *filename);
+
+UsbDumpState *usb_dump_init_alloc(const char *filename);
+#endif