BIP MinerHardwareBinaryProtocol: Difference between revisions

From Bitcoin Wiki
Jump to navigation Jump to search
Luke-jr (talk | contribs)
First draft
 
Luke-jr (talk | contribs)
Line 26: Line 26:


===Command Format===
===Command Format===
1 byte: request id
*1 byte: request id
1 byte: command id
*1 byte: command id
0x -- Modification commands (potentially dangerous)
**0x -- Modification commands (potentially dangerous)
4x -- Informational commands
**4x -- Informational commands
(high bit set for replies)
**(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: device number (ignored for some commands)
1 byte: status (should always be 00 for requests)
**00 is the MCU
00 -- success
**1-fe are FPGAs
80 -- failure
**ff for "all FPGAs"
N bytes: data
*1 byte: status (should always be 00 for requests)
**00 -- success
**80 -- failure
*N bytes: data


Commands less than 4 bytes should be ignored.
Commands less than 4 bytes should be ignored.
Additional data beyond what is expected should be ignored.
Additional data beyond what is expected should be ignored.


===Commands===
===Commands===

Revision as of 02:56, 28 June 2012

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