diff options
Diffstat (limited to 'utils/hwstub/include/hwstub_protocol.h')
| -rw-r--r-- | utils/hwstub/include/hwstub_protocol.h | 318 |
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__ */ |