BIP MinerHardwareBinaryProtocol

From Bitcoin Wiki
Revision as of 18:31, 8 June 2012 by Luke-jr (talk | contribs) (First draft)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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

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: packet length/type N bytes: packet data

Valid lengths are 1-250 (bytes). End of command is denoted by a length/type of ff. Abort command is denoted by a length/type of 00. ACK is denoted by a length/type of fe, and 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?). Length/types fa-fd are reserved.

Command Format

1 byte: request id 1 byte: command id 0x -- Modification commands (potentially dangerous) 4x -- Informational commands (high bit set for replies) 1 byte: device number (ignored for some commands) -- 00 is the MCU, 1-fe are FPGAs, and ff for "all FPGAs" 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

01 -- 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")
  • 4 bytes: software size
  • N bytes: software data

02 -- get/set clock speed

Data:

  • 1 byte: new clock speed (00 = don't change)

Reply (if getting):

  • 1 byte: current clock speed

03 -- get/set register(s)

Data:

  • 2 bytes: first register number
  • 2 bytes: number of registers to fetch/set
  • N bytes: new values for each register (omitted to read)

Reply (if reading):

  • 1 byte: width (in bits) of each register
  • N bytes: value of each register

04 -- watch register(s)

Data:

  • 2 bytes: first register number
  • 2 bytes: number of registers to watch
  • 1 byte: how long to watch, in seconds; 00 = cancel watch; ff = never expire

Reply (immediate):

  • 1 byte: width (in bits) of each register
  • N bytes: current value of each register

Notification (DEFERRED, with command=ff and same request id):

  • 2 bytes: number of registers changed
  • for each:
    • 2 bytes: register number
    • N bytes: value of register

40 -- ping

Device number ignored. Replies with same data given

41 -- get FPGA count

Device number ignored. Reply:

  • 1 byte: number of FPGAs

42 -- 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")
  • 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)

43 -- 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)

44 -- get temperature

Reply:

  • 1 byte: temperature in celcius

Examples

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 251 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