BIP MinerHardwareBinaryProtocol
BIP: ? Title: Protocol for Dedicated Mining Hardware Author: Luke Dashjr <[email protected]> Status: Draft Type: Standards Track Created: 08-06-2012
Contents
Abstract
Specification
This protocol is designed to be spoken only over a reliable (including error correction) lower-level protocol, such as USB-Serial or USB-CDC, to a local device.
Packet Format
- 1 byte: always FE
- 1 byte: packet length/type
- N bytes: packet data
- 4 bytes: packet data CRC32 (only for data packets)
Packet length/types:
- 00 — Abort
- 01 to ef — Data packet length (1 to 239 bytes)
- f0 to fc — Reserved
- fd — Bad packet (command aborted)
- fe — ACK
- ff — End of command
ACK should be sent in response to each 250-byte packet. Bulk data transfers, such as bitstream uploads, should wait until ACK is received before sending more packets (maybe? or does USB handle this for us too?).
CRC32 must include the string “mhbp” plus the packet length/type byte and all data; this is not used to prevent corruption (USB already guarantees that), but rather to avoid acting when something foreign sends stuff. If the CRC32 does not match, the device should send a “fd” packet back and abort the command.
Null-length commands (ie, “ff” without any valid data packets preceding it) must be ACK’d and ignored.
Anything up to the initial FE is ignored.
Command Format
- 1 byte: request id
- 1 byte: command id
- Cx — Modification commands (potentially dangerous)
- Dx — Replies to Modification commands
- Ex — Informational commands
- Fx — Replies to Informational commands
- 1 byte: device number (ignored for some commands)
- 00 is the controller
- 01 to fe are mining devices
- ff for “all mining devices”
- 1 byte: status (should always be 00 for requests)
- 00 — success
- 80 — failure
- N bytes: data
Commands less than 4 bytes should be ignored. Additional data beyond what is expected should be ignored.
Commands
c1 — program software
Data:
- 4 bytes: hardware version (big endian)
- 2 bytes: hardware manuf/authority
- 2 bytes: hardware model number
- 4 bytes: hardware specific information (“ID Code”)
- 2 bytes: hardware component
- 0000 — FPGA Bitstream
- 0100 — JTAG abstraction interface
- 4 bytes: software size
- N bytes: software data
c2 — get/set clock speed
Data:
- 4 bytes: new clock speed in Hz (omit to read only)
- 00000000 — minimum allowed
- ffffffff — maximum allowed
Reply (for both get and set):
- 4 bytes: current/new clock speed
c3 — start new job
Data:
- 1 byte: busy behaviour (what to do if there’s already a job running)
- 00 — cancel it (and all pending queued jobs) and start new job immediately
- 01 — error
- 02 — queue to run after current job finishes
- (data may end here to cancel all jobs and halt)
- 1 byte: job id
- 00 — Unusable
- N bytes: job data
- For standard Bitcoin kernels (but may be different for other kernels!):
- 32 bytes: SHA256 midstate
- 4 bytes: final 32 bits of transaction merkle root
- 4 bytes: block time header
- 4 bytes: block target in compact format (“bits”)
- 4 bytes (optional): first valid nonce (if omitted, 00000000)
- 4 bytes (optional): last valid nonce (if omitted, ffffffff)
- 2 bytes (optional): how many times to roll the time header (if omitted, 0000)
- For standard Bitcoin kernels (but may be different for other kernels!):
c4 — get/set register
Data:
- 2 bytes: register number
- ffff — valid share nonce
- Value:
- 1 byte: job id
- 00 — Unknown
- N bytes: nonce (4 bytes for standard Bitcoin kernels)
- 1 byte: job id
- Value:
- ffff — valid share nonce
- N bytes: new value (omitted to read)
Reply (if reading):
- N bytes: current value
c5 — watch register
Data:
- 2 bytes: register number
- 1 byte: how long to watch, in seconds
- 00 — cancel watch
- ff — never expire
Reply (immediately):
- N bytes: current value
Notification (when condition met, with command=ff and same request id):
- 2 bytes: register number
- N bytes: new value
e0 — ping
Device number ignored. Replies with same data given
e1 — get mining device count
Device number ignored. Reply:
- 1 byte: number of mining devices
e2 — hardware version
Reply:
- 4 bytes: hardware version (big endian)
- 2 bytes: hardware manuf/authority
- 2 bytes: hardware model number
- 4 bytes: hardware specific information (“ID Code”)
- 2 bytes: number of programmable hardware components
- 2*N bytes: hardware component ids
- 1 byte: length of hardware serial number
- N bytes: hardware serial number
- 1 byte: length of hardware model number
- N bytes: hardware model number (EUI-64 when available)
- 1 byte: length of human-readable hardware model
- N bytes: human-readable hardware model/version string (UTF-8)
e3 — software version
Reply:
- 4 bytes: software version (big endian)
- 1 byte: length of software-specific unique identifier (git commit?)
- N bytes: software-specific unique identifier
- 1 byte: length of human-readable software name
- N bytes: human-readable hardware model/version string (UTF-8)
- 2 byte: number of MHBP features supported
- 2*N bytes: MHBP features supported
- c310 — standard Bitcoin kernel interface
- c311 — standard Bitcoin kernel interface: nonce range
- c312 — standard Bitcoin kernel interface: roll time
- c400 — general register access
- c410 — “job id” tracking
- c500 — general register watching
- c501 — nonce register watching
e4 — get temperature
Reply:
- 1 byte: temperature in celcius
Examples
Needs updating
Get temperature of FPGA #2
> 04 00 44 02 00 ff < 05 00 c4 02 00 30 ff
> 34 00 03 01 00 0000 000b <32:midstate> <12:taildata> ff (assign job to registers) > 09 01 04 01 00 000e 0001 ff ff (setup watch on nonce-found register) < 04 00 83 01 00 ff < 09 01 84 01 00 20 ffffffff ff ... < 0c 01 ff 01 00 0001 000e <4:nonce> ff (nonce-found got updated) > 09 02 04 01 00 000e 0001 00 ff (clear nonce-found watch) < 09 02 84 01 00 20 <4:nonce> ff
Reset the command queue
To reset the command queue, send 244 zero bytes; this will pad-out any “open” packet, and send a zero-length for the next one to abort the command.
Twitter
Telegram
