BIP MinerHardwareBinaryProtocol

This page describes a BIP (Bitcoin Improvement Proposal). Please see BIP 2 for more information about BIPs and creating them. Please do not just create a wiki page.

  BIP: ?
  Title: Protocol for Dedicated Mining Hardware
  Author: Luke Dashjr <luke+bipmhbp@dashjr.org>
  Status: Draft
  Type: Standards Track
  Created: 08-06-2012

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.