aboutsummaryrefslogtreecommitdiffstats
path: root/firmware/libcommon/include/simtrace_prot.h
blob: eca844addfe642ccf3069f8686e12649efd06d7a (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
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
/* SIMtrace2 USB protocol
 *
 * (C) 2015-2017 by Harald Welte <hwelte@hmw-consulting.de>
 * (C) 2018 by sysmocom -s.f.m.c. GmbH, Author: Kevin Redon <kredon@sysmocom.de>
 *
 * 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 program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
 */
#pragma once

#include <stdint.h>
#include <stdbool.h>

/***********************************************************************
 * COMMON HEADER
 ***********************************************************************/

enum simtrace_msg_class {
	SIMTRACE_MSGC_GENERIC = 0,
	/* Card Emulation / Forwarding */
	SIMTRACE_MSGC_CARDEM,
	/* Modem Control (if modem is attached next to device) */
	SIMTRACE_MSGC_MODEM,
	/* Reader/phone-car/SIM communication sniff */
	SIMTRACE_MSGC_SNIFF,

	/* first vendor-specific request */
	_SIMTRACE_MGSC_VENDOR_FIRST = 127,
};

enum simtrace_msg_type_generic {
	/* Generic Error Message */
	SIMTRACE_CMD_DO_ERROR	= 0,
	/* Request/Response for simtrace_board_info */
	SIMTRACE_CMD_BD_BOARD_INFO,
};

/* SIMTRACE_MSGC_CARDEM */
enum simtrace_msg_type_cardem {
	/* TPDU Data to be transmitted to phone */
	SIMTRACE_MSGT_DT_CEMU_TX_DATA = 1,
	/* Set the ATR to be returned at phone-SIM reset */
	SIMTRACE_MSGT_DT_CEMU_SET_ATR,
	/* Get Statistics Request / Response */
	SIMTRACE_MSGT_BD_CEMU_STATS,
	/* Get Status Request / Response */
	SIMTRACE_MSGT_BD_CEMU_STATUS,
	/* Request / Confirm emulated card insert */
	SIMTRACE_MSGT_DT_CEMU_CARDINSERT,
	/* TPDU Data received from phomne */
	SIMTRACE_MSGT_DO_CEMU_RX_DATA,
	/* Indicate PTS request from phone */
	SIMTRACE_MSGT_DO_CEMU_PTS,
	/* Set configurable parameters */
	SIMTRACE_MSGT_BD_CEMU_CONFIG,
};

/* SIMTRACE_MSGC_MODEM */
enum simtrace_msg_type_modem {
	/* Modem Control: Reset an attached modem */
	SIMTRACE_MSGT_DT_MODEM_RESET = 1,
	/* Modem Control: Select local / remote SIM */
	SIMTRACE_MSGT_DT_MODEM_SIM_SELECT,
	/* Modem Control: Status (WWAN LED, SIM Presence) */
	SIMTRACE_MSGT_BD_MODEM_STATUS,
};

/* SIMTRACE_MSGC_SNIFF */
enum simtrace_msg_type_sniff {
	/* Status change (card inserted, reset, ...) */
	SIMTRACE_MSGT_SNIFF_CHANGE = 0,
	/* Fi/Di baudrate change */
	SIMTRACE_MSGT_SNIFF_FIDI,
	/* ATR data */
	SIMTRACE_MSGT_SNIFF_ATR,
	/* PPS (request or response) data */
	SIMTRACE_MSGT_SNIFF_PPS,
	/* TPDU data */
	SIMTRACE_MSGT_SNIFF_TPDU,
};

/* common message header */
struct simtrace_msg_hdr {
	uint8_t msg_class;	/* simtrace_msg_class */
	uint8_t msg_type;	/* simtrace_msg_type_xxx */
	uint8_t seq_nr;
	uint8_t slot_nr;	/* SIM slot number */
	uint16_t _reserved;
	uint16_t msg_len;	/* length including header */
	uint8_t payload[0];
} __attribute__ ((packed));

/***********************************************************************
 * Capabilities
 ***********************************************************************/

/* generic capabilities */
enum simtrace_capability_generic {
	/* compatible with 5V SIM card interface */
	SIMTRACE_CAP_VOLT_5V,
	/* compatible with 3.3V SIM card interface */
	SIMTRACE_CAP_VOLT_3V3,
	/* compatible with 1.8V SIM card interface */
	SIMTRACE_CAP_VOLT_1V8,
	/* Has LED1 */
	SIMTRACE_CAP_LED_1,
	/* Has LED2 */
	SIMTRACE_CAP_LED_2,
	/* Has Single-Pole Dual-Throw (local/remote SIM) */
	SIMTRACE_CAP_SPDT,
	/* Has Bus-Switch (trace / MITM) */
	SIMTRACE_CAP_BUS_SWITCH,
	/* Can read VSIM via ADC */
	SIMTRACE_CAP_VSIM_ADC,
	/* Can read temperature via ADC */
	SIMTRACE_CAP_TEMP_ADC,
	/* Supports DFU for firmware update */
	SIMTRACE_CAP_DFU,
	/* Supports Ctrl EP command for erasing flash / return to SAM-BA */
	SIMTRACE_CAP_ERASE_FLASH,
	/* Can read the status of card insert contact */
	SIMTRACE_CAP_READ_CARD_DET,
	/* Can control the status of a simulated card insert */
	SIMTRACE_CAP_ASSERT_CARD_DET,
	/* Can toggle the hardware reset of an attached modem */
	SIMTRACE_CAP_ASSERT_MODEM_RST,
};

/* vendor-specific capabilities of sysmocom devices */
enum simtrace_capability_vendor {
	/* Can erase a peer SAM3 controller */
	SIMTRACE_CAP_SYSMO_QMOD_ERASE_PEER,
	/* Can read/write an attached EEPROM */
	SIMTRACE_CAP_SYSMO_QMOD_RW_EEPROM,
	/* can reset an attached USB hub */
	SIMTRACE_CAP_SYSMO_QMOD_RESET_HUB,
};

/* SIMTRACE_CMD_BD_BOARD_INFO */
struct simtrace_board_info {
	struct {
		char manufacturer[32];
		char model[32];
		char version[32];
	} hardware;
	struct {
		/* who provided this software? */
		char provider[32];
		/* name of software image */
		char name[32];
		/* (git) version at build time */
		char version[32];
		/* built on which machine? */
		char buildhost[32];
		/* CRC-32 over software image */
		uint32_t crc;
	} software;
	struct {
		/* Maximum baud rate supported */
		uint32_t max_baud_rate;
	} speed;
	/* number of bytes of generic capability bit-mask */
	uint8_t cap_generic_bytes;
	/* number of bytes of vendor capability bit-mask */
	uint8_t cap_vendor_bytes;
	uint8_t data[0];
	/* cap_generic + cap_vendor */
} __attribute__ ((packed));

/***********************************************************************
 * CARD EMULATOR / FORWARDER
 ***********************************************************************/

/* indicates a TPDU header is present in this message */
#define CEMU_DATA_F_TPDU_HDR	0x00000001
/* indicates last part of transmission in this direction */
#define CEMU_DATA_F_FINAL	0x00000002
/* incdicates a PB is present and we should continue with TX */
#define CEMU_DATA_F_PB_AND_TX	0x00000004
/* incdicates a PB is present and we should continue with RX */
#define CEMU_DATA_F_PB_AND_RX	0x00000008

/* CEMU_USB_MSGT_DT_CARDINSERT */
struct cardemu_usb_msg_cardinsert {
	uint8_t card_insert;
} __attribute__ ((packed));

/* CEMU_USB_MSGT_DT_SET_ATR */
struct cardemu_usb_msg_set_atr {
	uint8_t atr_len;
	/* variable-length ATR data */
	uint8_t atr[0];
} __attribute__ ((packed));

/* CEMU_USB_MSGT_DT_TX_DATA */
struct cardemu_usb_msg_tx_data {
	uint32_t flags;
	uint16_t data_len;
	/* variable-length TPDU data */
	uint8_t data[0];
} __attribute__ ((packed));

/* CEMU_USB_MSGT_DO_RX_DATA */
struct cardemu_usb_msg_rx_data {
	uint32_t flags;
	uint16_t data_len;
	/* variable-length TPDU data */
	uint8_t data[0];
} __attribute__ ((packed));

#define CEMU_STATUS_F_VCC_PRESENT	0x00000001
#define CEMU_STATUS_F_CLK_ACTIVE	0x00000002
#define CEMU_STATUS_F_RCEMU_ACTIVE	0x00000004
#define CEMU_STATUS_F_CARD_INSERT	0x00000008
#define CEMU_STATUS_F_RESET_ACTIVE	0x00000010

/* CEMU_USB_MSGT_DO_STATUS */
struct cardemu_usb_msg_status {
	uint32_t flags;
	/* phone-applied target voltage in mV */
	uint16_t voltage_mv;
	/* Fi/Di related information */
	uint8_t fi;
	uint8_t di;
	uint8_t wi;
	uint32_t waiting_time;
} __attribute__ ((packed));

/* CEMU_USB_MSGT_DO_PTS */
struct cardemu_usb_msg_pts_info {
	uint8_t pts_len;
	/* PTS request as sent from reader */
	uint8_t req[6];
	/* PTS response as sent by card */
	uint8_t resp[6];
} __attribute__ ((packed));

/* CEMU_USB_MSGT_DO_ERROR */
struct cardemu_usb_msg_error {
	uint8_t severity;
	uint8_t subsystem;
	uint16_t code;
	uint8_t msg_len;
	/* human-readable error message */
	uint8_t msg[0];
} __attribute__ ((packed));

/* enable/disable the generation of DO_STATUS on IRQ endpoint */
#define CEMU_FEAT_F_STATUS_IRQ	0x00000001

/* SIMTRACE_MSGT_BD_CEMU_CONFIG */
struct cardemu_usb_msg_config {
	/* bit-mask of CEMU_FEAT_F flags */
	uint32_t features;
} __attribute__ ((packed));

/***********************************************************************
 * MODEM CONTROL
 ***********************************************************************/

/* SIMTRACE_MSGT_DT_MODEM_RESET */
struct st_modem_reset {
	/* 0: de-assert reset, 1: assert reset, 2: pulse reset */
	uint8_t asserted;
	/* if above is '2', duration of pulse in ms */
	uint16_t pulse_duration_msec;
} __attribute__((packed));

/* SIMTRACE_MSGT_DT_MODEM_SIM_SELECT */
struct st_modem_sim_select {
	/* remote (1), local (0) */
	uint8_t remote_sim;
} __attribute__((packed));

/* SIMTRACE_MSGT_BD_MODEM_STATUS */
#define ST_MDM_STS_BIT_WWAN_LED		(1 << 0)
#define ST_MDM_STS_BIT_CARD_INSERTED	(1 << 1)
struct st_modem_status {
	/* bit-field of supported status bits */
	uint8_t supported_mask;
	/* bit-field of current status bits */
	uint8_t status_mask;
	/* bit-field of changed status bits */
	uint8_t changed_mask;
} __attribute__((packed));

/***********************************************************************
 * SNIFF
 ***********************************************************************/

/* SIMTRACE_MSGT_SNIFF_CHANGE flags */
#define SNIFF_CHANGE_FLAG_CARD_INSERT (1<<0)
#define SNIFF_CHANGE_FLAG_CARD_EJECT (1<<1)
#define SNIFF_CHANGE_FLAG_RESET_ASSERT (1<<2)
#define SNIFF_CHANGE_FLAG_RESET_DEASSERT (1<<3)
#define SNIFF_CHANGE_FLAG_TIMEOUT_WT (1<<4)
/* SIMTRACE_MSGT_SNIFF_ATR, SIMTRACE_MSGT_SNIFF_PPS, SIMTRACE_MSGT_SNIFF_TPDU flags */
#define SNIFF_DATA_FLAG_ERROR_INCOMPLETE (1<<5)
#define SNIFF_DATA_FLAG_ERROR_MALFORMED (1<<6)
#define SNIFF_DATA_FLAG_ERROR_CHECKSUM (1<<7)

/* SIMTRACE_MSGT_SNIFF_CHANGE */
struct sniff_change {
	/* SIMTRACE_MSGT_SNIFF_CHANGE flags */
	uint32_t flags;
} __attribute__ ((packed));

/* SIMTRACE_MSGT_SNIFF_FIDI */
struct sniff_fidi {
	/* Fi/Di values as encoded in TA1 */
	uint8_t fidi;
} __attribute__ ((packed));

/* SIMTRACE_MSGT_SNIFF_ATR, SIMTRACE_MSGT_SNIFF_PPS, SIMTRACE_MSGT_SNIFF_TPDU */
struct sniff_data {
	/* data flags */
	uint32_t flags;
	/* data length */
	uint16_t length;
	/* data */
	uint8_t data[0];
} __attribute__ ((packed));