hwstub: rewrite and expand library

Rewrite the hwstub library in C++, with a clean and modular design.
The library was designed from the ground up to be aware of multithreading
issues and to handle memory allocation nicely with shared pointers.

Compared to the original library, it brings the following major features:
- support for JZ boot devices, it is very easy to add support for others
- support for network transparent operations (through sockets): both tcp
  and unix domains are support

Change-Id: I75899cb9c7aa938c17ede2bb3f468e7a55d625b4

1 files changed, 318 insertions, 0 deletions

diff --git a/utils/hwstub/include/hwstub_protocol.h b/utils/hwstub/include/hwstub_protocol.h
new file mode 100644
index 0000000000..39d2f2ebfe
--- /dev/null
+++ b/utils/hwstub/include/hwstub_protocol.h
@@ -0,0 +1,318 @@
+/***************************************************************************
+ *             __________               __   ___.
+ *   Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
+ *   Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
+ *   Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
+ *   Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
+ *                     \/            \/     \/    \/            \/
+ * $Id$
+ *
+ * Copyright (C) 2012 by Amaury Pouly
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ****************************************************************************/
+#ifndef __HWSTUB_PROTOCOL__
+#define __HWSTUB_PROTOCOL__
+
+#include <stdint.h>
+
+/**
+ * This file contains the data structures used in the USB and network protocol.
+ * All USB data uses the standard USB byte order which is little-endian.
+ */
+
+/**
+ * HWStub protocol version
+ */
+
+#define HWSTUB_VERSION_MAJOR    4
+#define HWSTUB_VERSION_MINOR    2
+
+#define HWSTUB_VERSION__(maj, min) #maj"."#min
+#define HWSTUB_VERSION_(maj, min) HWSTUB_VERSION__(maj, min)
+#define HWSTUB_VERSION  HWSTUB_VERSION_(HWSTUB_VERSION_MAJOR, HWSTUB_VERSION_MINOR)
+
+/**
+ * A device can use any VID:PID but in case hwstub is in full control of the
+ * device, the preferred VID:PID is the following.
+ */
+
+#define HWSTUB_USB_VID  0xfee1
+#define HWSTUB_USB_PID  0xdead
+
+/**
+ * The device class should be per interface and the hwstub interface must use
+ * the following class, subclass and protocol.
+ */
+
+#define HWSTUB_CLASS        0xff
+#define HWSTUB_SUBCLASS     0xde
+#define HWSTUB_PROTOCOL     0xad
+
+/**********************************
+ * Descriptors
+ **********************************/
+
+/**
+ * Descriptors can be retrieved using configuration descriptor or individually
+ * using the standard GetDescriptor request on the interface.
+ */
+
+#define HWSTUB_DT_VERSION   0x41 /* mandatory */
+#define HWSTUB_DT_LAYOUT    0x42 /* mandatory */
+#define HWSTUB_DT_TARGET    0x43 /* mandatory */
+#define HWSTUB_DT_STMP      0x44 /* mandatory for STMP */
+#define HWSTUB_DT_PP        0x45 /* mandatory for PP */
+#define HWSTUB_DT_JZ        0x46 /* mandatory for JZ */
+
+struct hwstub_version_desc_t
+{
+    uint8_t bLength;
+    uint8_t bDescriptorType;
+    /* full version information */
+    uint8_t bMajor;
+    uint8_t bMinor;
+    uint8_t bRevision;
+} __attribute__((packed));
+
+struct hwstub_layout_desc_t
+{
+    uint8_t bLength;
+    uint8_t bDescriptorType;
+    /* describe the range of memory used by the running code */
+    uint32_t dCodeStart;
+    uint32_t dCodeSize;
+    /* describe the range of memory used by the stack */
+    uint32_t dStackStart;
+    uint32_t dStackSize;
+    /* describe the range of memory available as a buffer */
+    uint32_t dBufferStart;
+    uint32_t dBufferSize;
+} __attribute__((packed));
+
+struct hwstub_stmp_desc_t
+{
+    uint8_t bLength;
+    uint8_t bDescriptorType;
+    /* Chip ID and revision */
+    uint16_t wChipID; /* 0x3780 for STMP3780 for example */
+    uint8_t bRevision; /* 0=TA1 on STMP3780 for example */
+    uint8_t bPackage; /* 0=169BGA for example */
+} __attribute__((packed));
+
+struct hwstub_pp_desc_t
+{
+    uint8_t bLength;
+    uint8_t bDescriptorType;
+    /* Chip ID and revision */
+    uint16_t wChipID; /* 0x5002 for PP5002 for example */
+    uint8_t bRevision[2]; /* 'B1' for B1 for example */
+} __attribute__((packed));
+
+struct hwstub_jz_desc_t
+{
+    uint8_t bLength;
+    uint8_t bDescriptorType;
+    /* Chip ID and revision */
+    uint16_t wChipID; /* 0x4760 for Jz4760 for example */
+    uint8_t bRevision; /* 0 for Jz4760, 'B' for JZ4760B */
+} __attribute__((packed));
+
+#define HWSTUB_TARGET_UNK       ('U' | 'N' << 8 | 'K' << 16 | ' ' << 24)
+#define HWSTUB_TARGET_STMP      ('S' | 'T' << 8 | 'M' << 16 | 'P' << 24)
+#define HWSTUB_TARGET_RK27      ('R' | 'K' << 8 | '2' << 16 | '7' << 24)
+#define HWSTUB_TARGET_PP        ('P' | 'P' << 8 | ' ' << 16 | ' ' << 24)
+#define HWSTUB_TARGET_ATJ       ('A' | 'T' << 8 | 'J' << 16 | ' ' << 24)
+#define HWSTUB_TARGET_JZ        ('J' | 'Z' << 8 | '4' << 16 | '7' << 24)
+
+struct hwstub_target_desc_t
+{
+    uint8_t bLength;
+    uint8_t bDescriptorType;
+    /* Target ID and name */
+    uint32_t dID;
+    char bName[58];
+} __attribute__((packed));
+
+/**
+ * Socket command packet header: any transfer (in both directions) start with this.
+ * All data is transmitted in network byte order.
+ */
+#define HWSTUB_NET_ARGS 4
+
+struct hwstub_net_hdr_t
+{
+    uint32_t magic; /* magic value (HWSERVER_MAGIC) */
+    uint32_t cmd; /* command (OR'ed with (N)ACK on response) */
+    uint32_t length; /* length of the data following this header */
+    uint32_t args[HWSTUB_NET_ARGS]; /* command arguments */
+} __attribute__((packed));
+
+/**
+ * Control commands
+ *
+ * These commands are sent to the interface, using the standard bRequest field
+ * of the SETUP packet. The wIndex contains the interface number. The wValue
+ * contains an ID which is used for requests requiring several transfers.
+ */
+#define HWSTUB_GET_LOG              0x40
+#define HWSTUB_READ                 0x41
+#define HWSTUB_READ2                0x42
+#define HWSTUB_WRITE                0x43
+#define HWSTUB_EXEC                 0x44
+#define HWSTUB_READ2_ATOMIC         0x45
+#define HWSTUB_WRITE_ATOMIC         0x46
+
+/* the following commands and the ACK/NACK mechanism are net only */
+#define HWSERVER_ACK(n) (0x100|(n))
+#define HWSERVER_ACK_MASK 0x100
+#define HWSERVER_NACK(n) (0x200|(n))
+#define HWSERVER_NACK_MASK 0x200
+
+#define HWSERVER_MAGIC              ('h' << 24 | 'w' << 16 | 's' << 8 | 't')
+
+#define HWSERVER_HELLO              0x400
+#define HWSERVER_GET_DEV_LIST       0x401
+#define HWSERVER_DEV_OPEN           0x402
+#define HWSERVER_DEV_CLOSE          0x403
+#define HWSERVER_BYE                0x404
+#define HWSERVER_GET_DESC           0x405
+#define HWSERVER_GET_LOG            0x406
+#define HWSERVER_READ               0x407
+#define HWSERVER_WRITE              0x408
+#define HWSERVER_EXEC               0x409
+
+/* net errors (always in arg[0] if command is NACKed) */
+#define HWERR_OK            0    /* success */
+#define HWERR_FAIL          1    /* general error from hwstub */
+#define HWERR_INVALID_ID    2    /* invalid id of the device */
+#define HWERR_DISCONNECTED  3    /* device got disconnected */
+
+/* read/write flags */
+#define HWSERVER_RW_ATOMIC          0x1
+
+/**********************************
+ * Control Protocol
+ **********************************/
+
+/**
+ * HWSTUB_GET_LOG:
+ * The log is returned as part of the control transfer.
+ */
+
+/**
+ * HWSTUB_READ and HWSTUB_READ2(_ATOMIC):
+ * Read a range of memory. The request works in two steps: first the host
+ * sends HWSTUB_READ with the parameters (address, length) and then
+ * a HWSTUB_READ2 to retrieve the buffer. Both requests must use the same
+ * ID in wValue, otherwise the second request will be STALLed.
+ * HWSTUB_READ2_ATOMIC behaves the same as HWSTUB_READ2 except that the read
+ * is guaranteed to be atomic (ie performed as a single memory access) and
+ * will be STALLed if atomicity can not be ensured.
+ */
+
+struct hwstub_read_req_t
+{
+    uint32_t dAddress;
+} __attribute__((packed));
+
+/**
+ * HWSTUB_WRITE:
+ * Write a range of memory. The payload starts with the following header, everything
+ * which follows is data.
+ * HWSTUB_WRITE_ATOMIC behaves the same except it is atomic. See HWSTUB_READ2_ATOMIC.
+ */
+struct hwstub_write_req_t
+{
+    uint32_t dAddress;
+} __attribute__((packed));
+
+/**
+ * HWSTUB_EXEC:
+ * Execute code at an address. Several options are available regarding ARM vs Thumb,
+ * jump vs call.
+ */
+
+#define HWSTUB_EXEC_ARM     (0 << 0) /* target code is ARM */
+#define HWSTUB_EXEC_THUMB   (1 << 0) /* target code is Thumb */
+#define HWSTUB_EXEC_JUMP    (0 << 1) /* branch, code will never turn */
+#define HWSTUB_EXEC_CALL    (1 << 1) /* call and expect return */
+
+struct hwstub_exec_req_t
+{
+    uint32_t dAddress;
+    uint16_t bmFlags;
+} __attribute__((packed));
+
+/**
+ * HWSERVER_HELLO:
+ * Say hello to the server, give protocol version and get server version.
+ * Send: args[0] = major << 8 | minor, no data
+ * Receive: args[0] = major << 8 | minor, no data
+ */
+
+/**
+ * HWSERVER_GET_DEV_LIST:
+ * Get device list.
+ * Send: no argument, no data.
+ * Receive: no argument, data contains a list of device IDs, each ID is a uint32_t
+ *          transmitted in network byte order.
+ */
+
+/**
+ * HWSERVER_DEV_OPEN:
+ * Open a device and return a handle.
+ * Send: args[0] = device ID, no data.
+ * Receive: args[0] = handle ID, no data.
+ */
+
+/**
+ * HWSERVER_DEV_CLOSE:
+ * Close a device handle.
+ * Send: args[0] = handle ID, no data.
+ * Receive: no argument, no data.
+ */
+
+/**
+ * HWSERVER_BYE:
+ * Say bye to the server, closing all devices and effectively stopping the communication.
+ * Send: no argument, no data
+ * Receive: no argument, no data
+ */
+
+/**
+ * HWSERVER_GET_DESC:
+ * Query a descriptor.
+ * Send: args[0] = handle ID, args[1] = desc ID, args[2] = requested length, no data
+ * Receive: no argument, data contains RAW descriptor (ie all fields are in little-endian)
+ */
+
+/**
+ * HWSERVER_GET_LOG:
+ * Query a descriptor.
+ * Send: args[0] = handle ID, args[1] = requested length, no data
+ * Receive: no argument, data contains log data
+ */
+
+/**
+ * HWSERVER_READ:
+ * Read data.
+ * Send: args[0] = handle ID, args[1] = addr, args[2] = length, args[3] = flags
+ * Receive: no argument, data read on device
+ */
+
+/**
+ * HWSERVER_WRITE:
+ * Read data.
+ * Send: args[0] = handle ID, args[1] = addr, args[2] = flags, data to write
+ * Receive: no data
+ */
+
+#endif /* __HWSTUB_PROTOCOL__ */