BIP MinerHardwareBinaryProtocol

BIP: ?
 Title: Protocol for Dedicated Mining Hardware
 Author: Luke Dashjr <luke+bipmhbp@dashjr.org>
 Status: Draft
 Type: Standards Track
 Created: 08-06-2012
==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)
====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)
* 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
====Mine a bitcoin share (with proper bitstream, on FPGA #1)====
 > 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.
==Motivation==
==Rationale==
==Backwards Compatibility==
==Reference Implementation==