Kévin Redon | 26a6609 | 2018-10-10 00:30:23 +0200 | [diff] [blame] | 1 | /* SIMtrace2 USB protocol |
| 2 | * |
| 3 | * (C) 2015-2017 by Harald Welte <hwelte@hmw-consulting.de> |
| 4 | * (C) 2018 by sysmocom -s.f.m.c. GmbH, Author: Kevin Redon <kredon@sysmocom.de> |
| 5 | * |
| 6 | * This program is free software; you can redistribute it and/or modify |
| 7 | * it under the terms of the GNU General Public License as published by |
| 8 | * the Free Software Foundation; either version 2 of the License, or |
| 9 | * (at your option) any later version. |
| 10 | * |
| 11 | * This program is distributed in the hope that it will be useful, |
| 12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 14 | * GNU General Public License for more details. |
| 15 | * |
| 16 | * You should have received a copy of the GNU General Public License |
| 17 | * along with this program; if not, write to the Free Software |
| 18 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA |
| 19 | */ |
| 20 | #pragma once |
| 21 | |
| 22 | #include <stdint.h> |
| 23 | #include <stdbool.h> |
| 24 | |
| 25 | /*********************************************************************** |
| 26 | * COMMON HEADER |
| 27 | ***********************************************************************/ |
| 28 | |
| 29 | enum simtrace_msg_class { |
| 30 | SIMTRACE_MSGC_GENERIC = 0, |
| 31 | /* Card Emulation / Forwarding */ |
| 32 | SIMTRACE_MSGC_CARDEM, |
| 33 | /* Modem Control (if modem is attached next to device) */ |
| 34 | SIMTRACE_MSGC_MODEM, |
| 35 | /* Reader/phone-car/SIM communication sniff */ |
| 36 | SIMTRACE_MSGC_SNIFF, |
| 37 | |
| 38 | /* first vendor-specific request */ |
| 39 | _SIMTRACE_MGSC_VENDOR_FIRST = 127, |
| 40 | }; |
| 41 | |
| 42 | enum simtrace_msg_type_generic { |
| 43 | /* Generic Error Message */ |
| 44 | SIMTRACE_CMD_DO_ERROR = 0, |
| 45 | /* Request/Response for simtrace_board_info */ |
| 46 | SIMTRACE_CMD_BD_BOARD_INFO, |
| 47 | }; |
| 48 | |
| 49 | /* SIMTRACE_MSGC_CARDEM */ |
| 50 | enum simtrace_msg_type_cardem { |
| 51 | /* TPDU Data to be transmitted to phone */ |
| 52 | SIMTRACE_MSGT_DT_CEMU_TX_DATA = 1, |
| 53 | /* Set the ATR to be returned at phone-SIM reset */ |
| 54 | SIMTRACE_MSGT_DT_CEMU_SET_ATR, |
| 55 | /* Get Statistics Request / Response */ |
| 56 | SIMTRACE_MSGT_BD_CEMU_STATS, |
| 57 | /* Get Status Request / Response */ |
| 58 | SIMTRACE_MSGT_BD_CEMU_STATUS, |
| 59 | /* Request / Confirm emulated card insert */ |
| 60 | SIMTRACE_MSGT_DT_CEMU_CARDINSERT, |
| 61 | /* TPDU Data received from phomne */ |
| 62 | SIMTRACE_MSGT_DO_CEMU_RX_DATA, |
| 63 | /* Indicate PTS request from phone */ |
| 64 | SIMTRACE_MSGT_DO_CEMU_PTS, |
| 65 | }; |
| 66 | |
| 67 | /* SIMTRACE_MSGC_MODEM */ |
| 68 | enum simtrace_msg_type_modem { |
| 69 | /* Modem Control: Reset an attached modem */ |
| 70 | SIMTRACE_MSGT_DT_MODEM_RESET = 1, |
| 71 | /* Modem Control: Select local / remote SIM */ |
| 72 | SIMTRACE_MSGT_DT_MODEM_SIM_SELECT, |
| 73 | /* Modem Control: Status (WWAN LED, SIM Presence) */ |
| 74 | SIMTRACE_MSGT_BD_MODEM_STATUS, |
| 75 | }; |
| 76 | |
| 77 | /* SIMTRACE_MSGC_SNIFF */ |
| 78 | enum simtrace_msg_type_sniff { |
| 79 | /* Status change (card inserted, reset, ...) */ |
| 80 | SIMTRACE_MSGT_SNIFF_CHANGE = 0, |
| 81 | /* Fi/Di baudrate change */ |
| 82 | SIMTRACE_MSGT_SNIFF_FIDI, |
| 83 | /* ATR data */ |
| 84 | SIMTRACE_MSGT_SNIFF_ATR, |
| 85 | /* PPS (request or response) data */ |
| 86 | SIMTRACE_MSGT_SNIFF_PPS, |
| 87 | /* TPDU data */ |
| 88 | SIMTRACE_MSGT_SNIFF_TPDU, |
| 89 | }; |
| 90 | |
| 91 | /* common message header */ |
| 92 | struct simtrace_msg_hdr { |
| 93 | uint8_t msg_class; /* simtrace_msg_class */ |
| 94 | uint8_t msg_type; /* simtrace_msg_type_xxx */ |
| 95 | uint8_t seq_nr; |
| 96 | uint8_t slot_nr; /* SIM slot number */ |
| 97 | uint16_t _reserved; |
| 98 | uint16_t msg_len; /* length including header */ |
| 99 | uint8_t payload[0]; |
| 100 | } __attribute__ ((packed)); |
| 101 | |
| 102 | /*********************************************************************** |
| 103 | * Capabilities |
| 104 | ***********************************************************************/ |
| 105 | |
| 106 | /* generic capabilities */ |
| 107 | enum simtrace_capability_generic { |
| 108 | /* compatible with 5V SIM card interface */ |
| 109 | SIMTRACE_CAP_VOLT_5V, |
| 110 | /* compatible with 3.3V SIM card interface */ |
| 111 | SIMTRACE_CAP_VOLT_3V3, |
| 112 | /* compatible with 1.8V SIM card interface */ |
| 113 | SIMTRACE_CAP_VOLT_1V8, |
| 114 | /* Has LED1 */ |
| 115 | SIMTRACE_CAP_LED_1, |
| 116 | /* Has LED2 */ |
| 117 | SIMTRACE_CAP_LED_2, |
| 118 | /* Has Single-Pole Dual-Throw (local/remote SIM) */ |
| 119 | SIMTRACE_CAP_SPDT, |
| 120 | /* Has Bus-Switch (trace / MITM) */ |
| 121 | SIMTRACE_CAP_BUS_SWITCH, |
| 122 | /* Can read VSIM via ADC */ |
| 123 | SIMTRACE_CAP_VSIM_ADC, |
| 124 | /* Can read temperature via ADC */ |
| 125 | SIMTRACE_CAP_TEMP_ADC, |
| 126 | /* Supports DFU for firmware update */ |
| 127 | SIMTRACE_CAP_DFU, |
| 128 | /* Supports Ctrl EP command for erasing flash / return to SAM-BA */ |
| 129 | SIMTRACE_CAP_ERASE_FLASH, |
| 130 | /* Can read the status of card insert contact */ |
| 131 | SIMTRACE_CAP_READ_CARD_DET, |
| 132 | /* Can control the status of a simulated card insert */ |
| 133 | SIMTRACE_CAP_ASSERT_CARD_DET, |
| 134 | /* Can toggle the hardware reset of an attached modem */ |
| 135 | SIMTRACE_CAP_ASSERT_MODEM_RST, |
| 136 | }; |
| 137 | |
| 138 | /* vendor-specific capabilities of sysmocom devices */ |
| 139 | enum simtrace_capability_vendor { |
| 140 | /* Can erase a peer SAM3 controller */ |
| 141 | SIMTRACE_CAP_SYSMO_QMOD_ERASE_PEER, |
| 142 | /* Can read/write an attached EEPROM */ |
| 143 | SIMTRACE_CAP_SYSMO_QMOD_RW_EEPROM, |
| 144 | /* can reset an attached USB hub */ |
| 145 | SIMTRACE_CAP_SYSMO_QMOD_RESET_HUB, |
| 146 | }; |
| 147 | |
| 148 | /* SIMTRACE_CMD_BD_BOARD_INFO */ |
| 149 | struct simtrace_board_info { |
| 150 | struct { |
| 151 | char manufacturer[32]; |
| 152 | char model[32]; |
| 153 | char version[32]; |
| 154 | } hardware; |
| 155 | struct { |
| 156 | /* who provided this software? */ |
| 157 | char provider[32]; |
| 158 | /* name of software image */ |
| 159 | char name[32]; |
| 160 | /* (git) version at build time */ |
| 161 | char version[32]; |
| 162 | /* built on which machine? */ |
| 163 | char buildhost[32]; |
| 164 | /* CRC-32 over software image */ |
| 165 | uint32_t crc; |
| 166 | } software; |
| 167 | struct { |
| 168 | /* Maximum baud rate supported */ |
| 169 | uint32_t max_baud_rate; |
| 170 | } speed; |
| 171 | /* number of bytes of generic capability bit-mask */ |
| 172 | uint8_t cap_generic_bytes; |
| 173 | /* number of bytes of vendor capability bit-mask */ |
| 174 | uint8_t cap_vendor_bytes; |
| 175 | uint8_t data[0]; |
| 176 | /* cap_generic + cap_vendor */ |
| 177 | } __attribute__ ((packed)); |
| 178 | |
| 179 | /*********************************************************************** |
| 180 | * CARD EMULATOR / FORWARDER |
| 181 | ***********************************************************************/ |
| 182 | |
| 183 | /* indicates a TPDU header is present in this message */ |
| 184 | #define CEMU_DATA_F_TPDU_HDR 0x00000001 |
| 185 | /* indicates last part of transmission in this direction */ |
| 186 | #define CEMU_DATA_F_FINAL 0x00000002 |
| 187 | /* incdicates a PB is present and we should continue with TX */ |
| 188 | #define CEMU_DATA_F_PB_AND_TX 0x00000004 |
| 189 | /* incdicates a PB is present and we should continue with RX */ |
| 190 | #define CEMU_DATA_F_PB_AND_RX 0x00000008 |
| 191 | |
| 192 | /* CEMU_USB_MSGT_DT_CARDINSERT */ |
| 193 | struct cardemu_usb_msg_cardinsert { |
| 194 | uint8_t card_insert; |
| 195 | } __attribute__ ((packed)); |
| 196 | |
| 197 | /* CEMU_USB_MSGT_DT_SET_ATR */ |
| 198 | struct cardemu_usb_msg_set_atr { |
| 199 | uint8_t atr_len; |
| 200 | /* variable-length ATR data */ |
| 201 | uint8_t atr[0]; |
| 202 | } __attribute__ ((packed)); |
| 203 | |
| 204 | /* CEMU_USB_MSGT_DT_TX_DATA */ |
| 205 | struct cardemu_usb_msg_tx_data { |
| 206 | uint32_t flags; |
| 207 | uint16_t data_len; |
| 208 | /* variable-length TPDU data */ |
| 209 | uint8_t data[0]; |
| 210 | } __attribute__ ((packed)); |
| 211 | |
| 212 | /* CEMU_USB_MSGT_DO_RX_DATA */ |
| 213 | struct cardemu_usb_msg_rx_data { |
| 214 | uint32_t flags; |
| 215 | uint16_t data_len; |
| 216 | /* variable-length TPDU data */ |
| 217 | uint8_t data[0]; |
| 218 | } __attribute__ ((packed)); |
| 219 | |
| 220 | #define CEMU_STATUS_F_VCC_PRESENT 0x00000001 |
| 221 | #define CEMU_STATUS_F_CLK_ACTIVE 0x00000002 |
| 222 | #define CEMU_STATUS_F_RCEMU_ACTIVE 0x00000004 |
| 223 | #define CEMU_STATUS_F_CARD_INSERT 0x00000008 |
| 224 | #define CEMU_STATUS_F_RESET_ACTIVE 0x00000010 |
| 225 | |
| 226 | /* CEMU_USB_MSGT_DO_STATUS */ |
| 227 | struct cardemu_usb_msg_status { |
| 228 | uint32_t flags; |
| 229 | /* phone-applied target voltage in mV */ |
| 230 | uint16_t voltage_mv; |
| 231 | /* Fi/Di related information */ |
| 232 | uint8_t fi; |
| 233 | uint8_t di; |
| 234 | uint8_t wi; |
| 235 | uint32_t waiting_time; |
| 236 | } __attribute__ ((packed)); |
| 237 | |
| 238 | /* CEMU_USB_MSGT_DO_PTS */ |
| 239 | struct cardemu_usb_msg_pts_info { |
| 240 | uint8_t pts_len; |
| 241 | /* PTS request as sent from reader */ |
| 242 | uint8_t req[6]; |
| 243 | /* PTS response as sent by card */ |
| 244 | uint8_t resp[6]; |
| 245 | } __attribute__ ((packed)); |
| 246 | |
| 247 | /* CEMU_USB_MSGT_DO_ERROR */ |
| 248 | struct cardemu_usb_msg_error { |
| 249 | uint8_t severity; |
| 250 | uint8_t subsystem; |
| 251 | uint16_t code; |
| 252 | uint8_t msg_len; |
| 253 | /* human-readable error message */ |
| 254 | uint8_t msg[0]; |
| 255 | } __attribute__ ((packed)); |
| 256 | |
| 257 | /*********************************************************************** |
| 258 | * MODEM CONTROL |
| 259 | ***********************************************************************/ |
| 260 | |
| 261 | /* SIMTRACE_MSGT_DT_MODEM_RESET */ |
| 262 | struct st_modem_reset { |
| 263 | /* 0: de-assert reset, 1: assert reset, 2: pulse reset */ |
| 264 | uint8_t asserted; |
| 265 | /* if above is '2', duration of pulse in ms */ |
| 266 | uint16_t pulse_duration_msec; |
| 267 | } __attribute__((packed)); |
| 268 | |
| 269 | /* SIMTRACE_MSGT_DT_MODEM_SIM_SELECT */ |
| 270 | struct st_modem_sim_select { |
| 271 | /* remote (1), local (0) */ |
| 272 | uint8_t remote_sim; |
| 273 | } __attribute__((packed)); |
| 274 | |
| 275 | /* SIMTRACE_MSGT_BD_MODEM_STATUS */ |
| 276 | #define ST_MDM_STS_BIT_WWAN_LED (1 << 0) |
| 277 | #define ST_MDM_STS_BIT_CARD_INSERTED (1 << 1) |
| 278 | struct st_modem_status { |
| 279 | /* bit-field of supported status bits */ |
| 280 | uint8_t supported_mask; |
| 281 | /* bit-field of current status bits */ |
| 282 | uint8_t status_mask; |
| 283 | /* bit-field of changed status bits */ |
| 284 | uint8_t changed_mask; |
| 285 | } __attribute__((packed)); |
| 286 | |
| 287 | /*********************************************************************** |
| 288 | * SNIFF |
| 289 | ***********************************************************************/ |
| 290 | |
| 291 | /* SIMTRACE_MSGT_SNIFF_CHANGE flags */ |
| 292 | #define SNIFF_CHANGE_FLAG_CARD_INSERT (1<<0) |
| 293 | #define SNIFF_CHANGE_FLAG_CARD_EJECT (1<<1) |
| 294 | #define SNIFF_CHANGE_FLAG_RESET_ASSERT (1<<2) |
| 295 | #define SNIFF_CHANGE_FLAG_RESET_DEASSERT (1<<3) |
| 296 | #define SNIFF_CHANGE_FLAG_TIMEOUT_WT (1<<4) |
| 297 | /* SIMTRACE_MSGT_SNIFF_ATR, SIMTRACE_MSGT_SNIFF_PPS, SIMTRACE_MSGT_SNIFF_TPDU flags */ |
| 298 | #define SNIFF_DATA_FLAG_ERROR_INCOMPLETE (1<<5) |
| 299 | #define SNIFF_DATA_FLAG_ERROR_MALFORMED (1<<6) |
| 300 | #define SNIFF_DATA_FLAG_ERROR_CHECKSUM (1<<7) |
| 301 | |
| 302 | /* SIMTRACE_MSGT_SNIFF_CHANGE */ |
| 303 | struct sniff_change { |
| 304 | /* SIMTRACE_MSGT_SNIFF_CHANGE flags */ |
| 305 | uint32_t flags; |
| 306 | } __attribute__ ((packed)); |
| 307 | |
| 308 | /* SIMTRACE_MSGT_SNIFF_FIDI */ |
| 309 | struct sniff_fidi { |
| 310 | /* Fi/Di values as encoded in TA1 */ |
| 311 | uint8_t fidi; |
| 312 | } __attribute__ ((packed)); |
| 313 | |
| 314 | /* SIMTRACE_MSGT_SNIFF_ATR, SIMTRACE_MSGT_SNIFF_PPS, SIMTRACE_MSGT_SNIFF_TPDU */ |
| 315 | struct sniff_data { |
| 316 | /* data flags */ |
| 317 | uint32_t flags; |
| 318 | /* data length */ |
| 319 | uint16_t length; |
| 320 | /* data */ |
| 321 | uint8_t data[0]; |
| 322 | } __attribute__ ((packed)); |