/ hf_protocol.h
hf_protocol.h
1 // 2 // Copyright 2013, 2014 HashFast Technologies LLC 3 // 4 // This program is free software; you can redistribute it and/or modify it 5 // under the terms of the GNU General Public License as published by the Free 6 // Software Foundation; either version 3 of the License, or (at your option) 7 // any later version. See COPYING for more details. 8 // 9 // Useful data structures and values for interfacing with HashFast products 10 // 11 // Version 1.1 12 // 13 14 #ifndef _HF_PROTOCOL_H_ 15 #define _HF_PROTOCOL_H_ 16 17 #define HF_PROTOCOL_VERSION ((0<<8)|1) 18 19 #define HF_PREAMBLE (uint8_t) 0xaa 20 #define HF_BROADCAST_ADDRESS (uint8_t) 0xff 21 #define HF_GWQ_ADDRESS (uint8_t) 254 22 23 // Serial protocol operation codes (Second header byte) 24 #define OP_NULL 0 25 #define OP_ROOT 1 26 #define OP_RESET 2 27 #define OP_PLL_CONFIG 3 28 #define OP_ADDRESS 4 29 #define OP_READDRESS 5 30 #define OP_HIGHEST 6 31 #define OP_BAUD 7 32 #define OP_UNROOT 8 33 34 #define OP_HASH 9 35 #define OP_NONCE 10 36 #define OP_ABORT 11 37 #define OP_STATUS 12 38 #define OP_GPIO 13 39 #define OP_CONFIG 14 40 #define OP_STATISTICS 15 41 #define OP_GROUP 16 42 #define OP_CLOCKGATE 17 43 44 // Conversions for the ADC readings from GN on-chip sensors 45 #define GN_CORE_VOLTAGE(a) ((float)(a)/256*1.2) 46 #define GN_DIE_TEMPERATURE(a) ((((float)(a)*240)/4096.0)-61.5) 47 48 // What to use in an OP_CONFIG hdata field to set thermal overload point to a given temp in degrees C 49 #define GN_THERMAL_CUTOFF(temp) ((uint16_t)(((temp)+61.5)*4096/240)) 50 51 // The sequence distance between a sent and received sequence number. 52 #define HF_SEQUENCE_DISTANCE(tx,rx) ((tx)>=(rx)?((tx)-(rx)):(info->num_sequence+(tx)-(rx))) 53 54 // Values the protocol field in the above structure may take 55 #define PROTOCOL_USB_MAPPED_SERIAL 0 56 #define PROTOCOL_GLOBAL_WORK_QUEUE 1 57 58 // Conversions for the board/module level sensors 59 #define M_VOLTAGE(a) ((float)(a)*19.0734e-6) 60 #define M_PHASE_CURRENT(a) ((float)(a)*0.794728597e-3) 61 62 // Values info->device_type can take 63 #define HFD_G1 1 // HashFast G-1 GN ASIC 64 #define HFD_VC709 128 65 #define HFD_ExpressAGX 129 66 67 // USB interface specific operation codes 68 #define OP_USB_INIT 128 // Initialize USB interface details 69 #define OP_GET_TRACE 129 // Send back the trace buffer if present 70 #define OP_LOOPBACK_USB 130 71 #define OP_LOOPBACK_UART 131 72 #define OP_DFU 132 // Jump into the boot loader 73 #define OP_USB_SHUTDOWN 133 // Initialize USB interface details 74 #define OP_DIE_STATUS 134 // Die status. There are 4 die per ASIC 75 #define OP_GWQ_STATUS 135 // Global Work Queue protocol status 76 #define OP_WORK_RESTART 136 // Stratum work restart regime 77 #define OP_USB_STATS1 137 // Statistics class 1 78 #define OP_USB_GWQSTATS 138 // GWQ protocol statistics 79 #define OP_USB_NOTICE 139 // Asynchronous notification event 80 #define OP_PING 140 // Echo 81 #define OP_CORE_MAP 141 // Return core map 82 #define OP_VERSION 142 // Version information 83 #define OP_FAN 143 // Set Fan Speed 84 #define OP_NAME 144 // System name write/read 85 #define OP_USB_DEBUG 255 86 87 // HashFast vendor and product ID's 88 #define HF_USB_VENDOR_ID 0x297c 89 #define HF_USB_PRODUCT_ID_G1 0x0001 90 91 // If this bit is set, search forward for other nonce(s) 92 #define HF_NTIME_MASK 0xfff // Mask for for ntime 93 #define HF_NONCE_SEARCH 0x1000 // Search bit in candidate_nonce -> ntime 94 95 // 96 // Fault codes that can be returned in struct hf_usb_init_base.operation_status 97 // 98 #define E_RESET_TIMEOUT 1 99 #define E_ADDRESS_TIMEOUT 2 100 #define E_CLOCKGATE_TIMEOUT 3 101 #define E_CONFIG_TIMEOUT 4 102 #define E_EXCESS_CORE_FAILURES 5 103 #define E_TOTAL_CORE_FAILURES 6 104 #define E_TOO_MANY_GROUPS 7 105 #define E_NO_SLAVES 8 106 #define E_SLAVE_COMM 9 107 #define E_MAIN_POWER_BAD 10 108 #define E_SECONDARY_POWER_BAD 11 109 #define E_BOARD_1 12 110 #define E_BOARD_2 13 111 #define E_BOARD_3 14 112 #define E_BOARD_4 15 113 #define E_BOARD_5 16 114 #define E_CORE_POWER_FAULT 17 115 #define E_BAUD_TIMEOUT 18 116 #define E_ADDRESS_FAILURE 19 117 #define E_IR_PROG_FAILURE 20 118 #define E_MIXED_MISMATCH 21 119 #define E_MIXED_TIMEOUT 22 120 121 #define U32SIZE(x) (sizeof(x)/sizeof(uint32_t)) 122 123 // Baud rate vs. code for gpi[7:5] coming out of reset 124 #define BAUD_RATE_PWRUP_0 115200 125 #define BAUD_RATE_PWRUP_1 9600 126 #define BAUD_RATE_PWRUP_2 38400 127 #define BAUD_RATE_PWRUP_3 57600 128 #define BAUD_RATE_PWRUP_4 230400 129 #define BAUD_RATE_PWRUP_5 576000 130 #define BAUD_RATE_PWRUP_6 921600 131 #define BAUD_RATE_PWRUP_7 1152000 132 133 // OP_WORK_RESTART hash clock change methods. 134 // 135 // May be issued *infrequently* by the host to adjust hash clock rate for thermal control 136 // The "hdata" field, if non zero, contains adjustment instructions. Bits 15:12 of "hdata" 137 // contain the adjustment type according to the following code, and bits 11:0 contain the 138 // associated value. Examples: 139 // hdata = (1<<12)|550 = Set hash clock rate to 550 Mhz 140 // hdata = (4<<12)|1 = Increase hash clock rate by 1% 141 // hdata = (6<<12) = Go back to whatever the "original" OP_USB_INIT settings were 142 // 143 // Finally, if 4 bytes of "data" follows the OP_WORK_RESTART header, then that data is taken 144 // as a little endian bitmap, bit set = enable clock change to that die, bit clear = don't 145 // change clock on that die, i.e. considered as a uint32_t, then 0x1 = die 0, 0x2 = die 1 etc. 146 147 #define WR_NO_CHANGE 0 148 #define WR_CLOCK_VALUE 1 149 #define WR_MHZ_INCREASE 2 150 #define WR_MHZ_DECREASE 3 151 #define WR_PERCENT_INCREASE 4 152 #define WR_PERCENT_DECREASE 5 153 #define WR_REVERT 6 154 155 #define WR_COMMAND_SHIFT 12 156 157 // Structure definitions, LE platforms 158 159 #if __BYTE_ORDER == __BIG_ENDIAN && !defined(WIN32) 160 #include "hf_protocol_be.h" 161 #else 162 // Generic header 163 struct hf_header { 164 uint8_t preamble; // Always 0xaa 165 uint8_t operation_code; 166 uint8_t chip_address; 167 uint8_t core_address; 168 uint16_t hdata; // Header specific data 169 uint8_t data_length; // .. of data frame to follow, in 4 byte blocks, 0=no data 170 uint8_t crc8; // Computed across bytes 1-6 inclusive 171 } __attribute__((packed,aligned(4))); // 8 bytes total 172 173 // Header specific to OP_PLL_CONFIG 174 struct hf_pll_config { 175 uint8_t preamble; 176 uint8_t operation_code; 177 uint8_t chip_address; 178 179 uint8_t pll_divr:6; 180 uint8_t pll_bypass:1; 181 uint8_t pll_reset:1; 182 183 uint8_t pll_divf; 184 185 uint8_t spare1:1; // Must always be 0 186 uint8_t pll_divq:3; 187 uint8_t pll_range:3; 188 uint8_t pll_fse:1; // Must always be 1 189 190 uint8_t data_length; // Always 0 191 uint8_t crc8; // Computed across bytes 1-6 inclusive 192 } __attribute__((packed,aligned(4))); // 8 bytes total 193 194 // OP_HASH serial data 195 struct hf_hash_serial { 196 uint8_t midstate[32]; // Computed from first half of block header 197 uint8_t merkle_residual[4]; // From block header 198 uint32_t timestamp; // From block header 199 uint32_t bits; // Actual difficulty target for block header 200 uint32_t starting_nonce; // Usually set to 0 201 uint32_t nonce_loops; // How many nonces to search, or 0 for 2^32 202 uint16_t ntime_loops; // How many times to roll timestamp, or 0 203 uint8_t search_difficulty; // Search difficulty to use, # of '0' digits required 204 uint8_t option; 205 uint8_t group; 206 uint8_t spare3[3]; 207 } __attribute__((packed,aligned(4))); 208 209 // OP_HASH usb data - header+data = 64 bytes 210 struct hf_hash_usb { 211 uint8_t midstate[32]; // Computed from first half of block header 212 uint8_t merkle_residual[4]; // From block header 213 uint32_t timestamp; // From block header 214 uint32_t bits; // Actual difficulty target for block header 215 uint32_t starting_nonce; // Usually set to 0 216 uint32_t nonce_loops; // How many nonces to search, or 0 for 2^32 217 uint16_t ntime_loops; // How many times to roll timestamp, or 0 218 uint8_t search_difficulty; // Search difficulty to use, # of '0' digits required 219 uint8_t group; // Non-zero for valid group 220 } __attribute__((packed,aligned(4))); 221 222 // OP_NONCE data 223 struct hf_candidate_nonce { 224 uint32_t nonce; // Candidate nonce 225 uint16_t sequence; // Sequence number from corresponding OP_HASH 226 uint16_t ntime; // ntime offset, if ntime roll occurred, in LS 12 bits 227 // If b12 set, search forward next 128 nonces to find solution(s) 228 } __attribute__((packed,aligned(4))); 229 230 // OP_CONFIG data 231 struct hf_config_data { 232 uint16_t status_period:11; // Periodic status time, msec 233 uint16_t enable_periodic_status:1; // Send periodic status 234 uint16_t send_status_on_core_idle:1; // Schedule status whenever core goes idle 235 uint16_t send_status_on_pending_empty:1; // Schedule status whenever core pending goes idle 236 uint16_t pwm_active_level:1; // Active level of PWM outputs, if used 237 uint16_t forward_all_privileged_packets:1; // Forward priv pkts -- diagnostic 238 uint8_t status_batch_delay; // Batching delay, time to wait before sending status 239 uint8_t watchdog:7; // Watchdog timeout, seconds 240 uint8_t disable_sensors:1; // Diagnostic 241 242 uint8_t rx_header_timeout:7; // Header timeout in char times 243 uint8_t rx_ignore_header_crc:1; // Ignore rx header crc's (diagnostic) 244 uint8_t rx_data_timeout:7; // Data timeout in char times / 16 245 uint8_t rx_ignore_data_crc:1; // Ignore rx data crc's (diagnostic) 246 uint8_t stats_interval:7; // Minimum interval to report statistics (seconds) 247 uint8_t stat_diagnostic:1; // Never set this 248 uint8_t measure_interval; // Die temperature measurement interval (msec) 249 250 uint32_t one_usec:12; // How many LF clocks per usec. 251 uint32_t max_nonces_per_frame:4; // Maximum # of nonces to combine in a single frame 252 uint32_t voltage_sample_points:8; // Bit mask for sample points (up to 5 bits set) 253 uint32_t pwm_phases:2; // phases - 1 254 uint32_t trim:4; // Trim value for temperature measurements 255 uint32_t clock_diagnostic:1; // Never set this 256 uint32_t forward_all_packets:1; // Forward everything - diagnostic. 257 258 uint16_t pwm_period; // Period of PWM outputs, in reference clock cycles 259 uint16_t pwm_pulse_period; // Initial count, phase 0 260 } __attribute__((packed,aligned(4))); 261 262 // OP_GROUP data 263 struct hf_group_data { 264 uint16_t nonce_msoffset; // This value << 16 added to starting nonce 265 uint16_t ntime_offset; // This value added to timestamp 266 } __attribute__((packed,aligned(4))); 267 268 // Structure of the monitor fields for G-1, returned in OP_STATUS, core bitmap follows this 269 struct hf_g1_monitor { 270 uint16_t die_temperature; // Die temperature ADC count 271 uint8_t core_voltage[6]; // Core voltage 272 // [0] = main sensor 273 // [1]-[5] = other positions 274 } __attribute__((packed,aligned(4))); 275 276 // What comes back in the body of an OP_STATISTICS frame (On die statistics) 277 struct hf_statistics { 278 uint8_t rx_header_crc; // Header CRC error's 279 uint8_t rx_body_crc; // Data CRC error's 280 uint8_t rx_header_timeouts; // Header timeouts 281 uint8_t rx_body_timeouts; // Data timeouts 282 uint8_t core_nonce_fifo_full; // Core nonce Q overrun events 283 uint8_t array_nonce_fifo_full; // System nonce Q overrun events 284 uint8_t stats_overrun; // Overrun in statistics reporting 285 uint8_t spare; 286 } __attribute__((packed,aligned(4))); 287 288 289 //////////////////////////////////////////////////////////////////////////////// 290 // USB protocol data structures 291 //////////////////////////////////////////////////////////////////////////////// 292 293 // Convenience header specific to OP_USB_INIT 294 struct hf_usb_init_header { 295 uint8_t preamble; // Always 0xaa 296 uint8_t operation_code; 297 uint8_t spare1; 298 299 uint8_t protocol:3; // Which protocol to use 300 uint8_t user_configuration:1; // Use the following configuration data 301 uint8_t pll_bypass:1; // Force PLL bypass, hash clock = ref clock 302 uint8_t no_asic_initialization:1; // Do not perform automatic ASIC initialization 303 uint8_t do_atspeed_core_tests:1; // Do core tests at speed, return second bitmap 304 uint8_t shed_supported:1; // Host supports gwq status shed_count 305 306 uint16_t hash_clock; // Requested hash clock frequency 307 308 uint8_t data_length; // .. of data frame to follow, in 4 byte blocks 309 uint8_t crc8; // Computed across bytes 1-6 inclusive 310 } __attribute__((packed,aligned(4))); // 8 bytes total 311 312 // Options (only if present) that may be appended to the above header 313 // Each option involving a numerical value will only be in effect if the value is non-zero 314 // This allows the user to select only those options desired for modification. Do not 315 // use this facility unless you are an expert - loading inconsistent settings will not work. 316 struct hf_usb_init_options { 317 uint16_t group_ntime_roll; // Total ntime roll amount per group 318 uint16_t core_ntime_roll; // Total core ntime roll amount 319 uint8_t low_operating_temp_limit; // Lowest normal operating limit 320 uint8_t high_operating_temp_limit; // Highest normal operating limit 321 uint16_t spare; 322 } __attribute__((packed,aligned(4))); 323 324 // Base item returned from device for OP_USB_INIT 325 struct hf_usb_init_base { 326 uint16_t firmware_rev; // Firmware revision # 327 uint16_t hardware_rev; // Hardware revision # 328 uint32_t serial_number; // Board serial number 329 uint8_t operation_status; // Reply status for OP_USB_INIT (0 = success) 330 uint8_t extra_status_1; // Extra reply status information, code specific 331 uint16_t sequence_modulus; // Sequence numbers are to be modulo this 332 uint16_t hash_clockrate; // Actual hash clock rate used (nearest Mhz) 333 uint16_t inflight_target; // Target inflight amount for GWQ protocol 334 } __attribute__((packed,aligned(4))); 335 336 // The above base item (16 bytes) is followed by the struct hf_config_data (16 bytes) actually 337 // used internally (so users may modify non-critical fields by doing subsequent 338 // OP_CONFIG operations). This is followed by a device specific "core good" bitmap (unless the 339 // user disabled initialization), and optionally by an at-speed "core good" bitmap. 340 341 342 // Information in an OP_DIE_STATUS frame. This is for one die - there are four per ASIC. 343 // Board level phase current and voltage sensors are likely to disappear in later production models. 344 struct hf_g1_die_data { 345 struct hf_g1_monitor die; // Die sensors - 8 bytes 346 uint16_t phase_currents[4]; // Phase currents (0 if unavailable) 347 uint16_t voltage; // Voltage at device boundary (0 if unavailable) 348 uint16_t temperature; // Regulator temp sensor 349 uint16_t tacho; // See documentation 350 uint16_t spare; 351 } __attribute__((packed,aligned(4))); // 24 bytes total 352 353 354 // Information for an OP_GWQ_STATUS frame 355 // If sequence_head == sequence_tail, then there is no active work and sequence_head is invalid 356 struct hf_gwq_data { 357 uint64_t hash_count; // Add this to host's cumulative hash count 358 uint16_t sequence_head; // The latest, internal, active sequence # 359 uint16_t sequence_tail; // The latest, internal, inactive sequence # 360 uint16_t shed_count; // # of cores have been shedded for thermal control 361 uint16_t spare; 362 } __attribute__((packed,aligned(4))); 363 364 365 // Information for an OP_USB_STATS1 frame - Communication statistics 366 struct hf_usb_stats1 { 367 // USB incoming 368 uint16_t usb_rx_preambles; 369 uint16_t usb_rx_receive_byte_errors; 370 uint16_t usb_rx_bad_hcrc; 371 372 // USB outgoing 373 uint16_t usb_tx_attempts; 374 uint16_t usb_tx_packets; 375 uint16_t usb_tx_timeouts; 376 uint16_t usb_tx_incompletes; 377 uint16_t usb_tx_endpointstalled; 378 uint16_t usb_tx_disconnected; 379 uint16_t usb_tx_suspended; 380 381 // Internal UART transmit 382 uint16_t uart_tx_queue_dma; 383 uint16_t uart_tx_interrupts; 384 385 // Internal UART receive 386 uint16_t uart_rx_preamble_ints; 387 uint16_t uart_rx_missed_preamble_ints; 388 uint16_t uart_rx_header_done; 389 uint16_t uart_rx_data_done; 390 uint16_t uart_rx_bad_hcrc; 391 //uint16_t uart_rx_bad_crc32; 392 uint16_t uart_rx_bad_dma; 393 uint16_t uart_rx_short_dma; 394 uint16_t uart_rx_buffers_full; 395 396 uint8_t max_tx_buffers; // Maximum # of send buffers ever used 397 uint8_t max_rx_buffers; // Maximum # of receive buffers ever used 398 } __attribute__((packed,aligned(4))); 399 400 // Information for an OP_USB_NOTICE frame 401 struct hf_usb_notice_data { 402 uint32_t extra_data; // Depends on notification code 403 char message[]; // NULL terminated, little endian byte order 404 }; 405 #endif 406 407 #endif