summaryrefslogtreecommitdiffstats
path: root/utils/hwstub/hwstub_protocol.h
blob: f47ce3b5db41e5dfa229c2fee4ec8b53056e1bb6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
/***************************************************************************
 *             __________               __   ___.
 *   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__

#define HWSTUB_CLASS        0xfe
#define HWSTUB_SUBCLASS     0xac
#define HWSTUB_PROTOCOL     0x1d

#define HWSTUB_VERSION_MAJOR    2
#define HWSTUB_VERSION_MINOR    11
#define HWSTUB_VERSION_REV      1

#define HWSTUB_USB_VID  0xfee1
#define HWSTUB_USB_PID  0xdead

/**
 * Control commands
 *
 * These commands are sent to the device, using the standard bRequest field
 * of the SETUP packet. This is to take advantage of both wIndex and wValue
 * although it would have been more correct to send them to the interface.
 */

/* list of commands */
#define HWSTUB_GET_INFO     0 /* mandatory */
#define HWSTUB_GET_LOG      1 /* optional */
#define HWSTUB_RW_MEM       2 /* optional */
#define HWSTUB_CALL         3 /* optional */
#define HWSTUB_JUMP         4 /* optional */
#define HWSTUB_STOP         5 /* optional */

/**
 * HWSTUB_GET_INFO: get some information about an aspect of the device.
 * The wIndex field of the SETUP specifies which information to get. */

/* list of possible information */
#define HWSTUB_INFO_VERSION     0 /* mandatory */
#define HWSTUB_INFO_LAYOUT      1 /* mandatory */
#define HWSTUB_INFO_STMP        2 /* optional */
#define HWSTUB_INFO_FEATURES    3 /* mandatory */
#define HWSTUB_INFO_TARGET      4 /* mandatory */

struct usb_resp_info_version_t
{
    uint8_t major;
    uint8_t minor;
    uint8_t revision;
} __attribute__((packed));

struct usb_resp_info_layout_t
{
    /* describe the range of memory used by the running code */
    uint32_t oc_code_start;
    uint32_t oc_code_size;
    /* describe the range of memory used by the stack */
    uint32_t oc_stack_start;
    uint32_t oc_stack_size;
    /* describe the range of memory available as a buffer */
    uint32_t oc_buffer_start;
    uint32_t oc_buffer_size;
} __attribute__((packed));

struct usb_resp_info_stmp_t
{
    uint16_t chipid; /* 0x3780 for STMP3780 for example */
    uint8_t rev; /* 0=TA1 on STMP3780 for example */
    uint8_t is_supported; /* 1 if the chip is supported */
} __attribute__((packed));

/* list of possible features */
#define HWSTUB_FEATURE_LOG      (1 << 0)
#define HWSTUB_FEATURE_MEM      (1 << 1)
#define HWSTUB_FEATURE_CALL     (1 << 2)
#define HWSTUB_FEATURE_JUMP     (1 << 3)
#define HWSTUB_FEATURE_STOP     (1 << 4)

struct usb_resp_info_features_t
{
    uint32_t feature_mask;
};

#define HWSTUB_TARGET_UNK       ('U' | 'N' << 8 | 'K' << 16 | ' ' << 24)
#define HWSTUB_TARGET_STMP      ('S' | 'T' << 8 | 'M' << 16 | 'P' << 24)

struct usb_resp_info_target_t
{
    uint32_t id;
    char name[60];
};

/**
 * HWSTUB_GET_LOG: only if has HWSTUB_FEATURE_LOG.
 * The log is returned as part of the control transfer.
 */

/**
 * HWSTUB_RW_MEM: only if has HWSTUB_FEATURE_MEM.
 * The 32-bit address is split into two parts.
 * The low 16-bit are stored in wValue and the upper
 * 16-bit are stored in wIndex. Depending on the transfer direction,
 * the transfer is either a read or a write.
 * The read/write on the device are guaranteed to be 16-bit/32-bit when
 * possible, making it suitable to read/write registers. */

/**
 * HWSTUB_x: only if has HWSTUB_FEATURE_x where x=CALL or JUMP.
 * The 32-bit address is split into two parts.
 * The low 16-bit are stored in wValue and the upper
 * 16-bit are stored in wIndex. Depending on the transfer direction,
 * the transfer is either a read or a write. */

/**
 * HWSTUB_STOP: only if has HWSTUB_FEATURE_STOP.
 * Stop hwstub. Several methods can be employed (not all may be supported).
 * The method is stored in wValue and interpreted as follows:
 * - reboot: immediately reboot the device
 * - off: wait for USB disconnection and power off */
#define HWSTUB_STOP_REBOOT  0
#define HWSTUB_STOP_OFF     1

#endif /* __HWSTUB_PROTOCOL__ */