Mailbox Inter-domain Communication Protocol

enum xcl_mailbox_request

List of all mailbox request OPCODE. Some OP code requires arguments, which is defined as corresponding data structures below. Response to the request usually is a int32_t containing the error code. Some responses are more complicated and require a data structure, which is also defined below in this file.

Constants

XCL_MAILBOX_REQ_UNKNOWN
invalid OP code
XCL_MAILBOX_REQ_TEST_READY
test msg is ready (post only, internal test only)
XCL_MAILBOX_REQ_TEST_READ
fetch test msg from peer (internal test only)
XCL_MAILBOX_REQ_LOCK_BITSTREAM
lock down xclbin on mgmt pf (not implemented)
XCL_MAILBOX_REQ_UNLOCK_BITSTREAM
unlock xclbin on mgmt pf (not implemented)
XCL_MAILBOX_REQ_HOT_RESET
request mgmt pf driver to reset the board
XCL_MAILBOX_REQ_FIREWALL
firewall trip detected on mgmt pf (post only)
XCL_MAILBOX_REQ_LOAD_XCLBIN_KADDR
download xclbin (pointed to by a pointer)
XCL_MAILBOX_REQ_LOAD_XCLBIN
download xclbin (bitstream is in payload)
XCL_MAILBOX_REQ_RECLOCK
set clock frequency
XCL_MAILBOX_REQ_PEER_DATA
read specified data from peer
XCL_MAILBOX_REQ_USER_PROBE
for user pf to probe the peer mgmt pf
XCL_MAILBOX_REQ_MGMT_STATE
for mgmt pf to notify user pf of its state change (post only)
XCL_MAILBOX_REQ_CHG_SHELL
shell change is required on mgmt pf (post only)
XCL_MAILBOX_REQ_PROGRAM_SHELL
request mgmt pf driver to reprogram shell
XCL_MAILBOX_REQ_READ_P2P_BAR_ADDR
undescribed
struct xcl_mailbox_req_bitstream_lock

MAILBOX_REQ_LOCK_BITSTREAM and MAILBOX_REQ_UNLOCK_BITSTREAM payload type

Definition

struct xcl_mailbox_req_bitstream_lock {
  uint64_t reserved;
  uint8_t uuid;
};

Members

reserved
reserved for future use
uuid
uuid of the xclbin
enum xcl_group_kind

Groups of data that can be fetched from mgmt side

Constants

XCL_SENSOR
all kinds of sensor readings
XCL_ICAP
ICAP IP related information
XCL_BDINFO
Board Info, serial_num, mac_address
XCL_MIG_ECC
ECC statistics
XCL_FIREWALL
AF detected time, status
XCL_DNA
Device DNA information
XCL_SUBDEV
PLP subdevices information
struct xcl_board_info

Data structure used to fetch BDINFO group

Definition

struct xcl_board_info {
};

Members

struct xcl_sensor

Data structure used to fetch SENSOR group

Definition

struct xcl_sensor {
};

Members

struct xcl_pr_region

Data structure used to fetch ICAP group

Definition

struct xcl_pr_region {
};

Members

struct xcl_mig_ecc

Data structure used to fetch MIG_ECC group

Definition

struct xcl_mig_ecc {
};

Members

struct xcl_firewall

Data structure used to fetch FIREWALL group

Definition

struct xcl_firewall {
};

Members

struct xcl_dna

Data structure used to fetch DNA group

Definition

struct xcl_dna {
};

Members

struct xcl_mailbox_subdev_peer

MAILBOX_REQ_PEER_DATA payload type

Definition

struct xcl_mailbox_subdev_peer {
  enum xcl_group_kind kind;
  uint64_t size;
};

Members

kind
data group
size
buffer size for receiving response
struct xcl_mailbox_conn

MAILBOX_REQ_USER_PROBE payload type

Definition

struct xcl_mailbox_conn {
  uint64_t kaddr;
  uint64_t paddr;
  uint32_t crc32;
  uint32_t version;
};

Members

kaddr
KVA of the verification data buffer
paddr
physical addresss of the verification data buffer
crc32
CRC value of the verification data buffer
version
protocol version supported by peer
struct xcl_mailbox_conn_resp

MAILBOX_REQ_USER_PROBE response payload type

Definition

struct xcl_mailbox_conn_resp {
  uint32_t version;
  uint64_t conn_flags;
  uint64_t chan_switch;
  char comm_id;
};

Members

version
protocol version should be used
conn_flags
connection status
chan_switch
bitmap to indicate SW / HW channel for each OP code msg
comm_id
user defined cookie
struct xcl_mailbox_peer_state

MAILBOX_REQ_MGMT_STATE payload type

Definition

struct xcl_mailbox_peer_state {
  uint64_t state_flags;
};

Members

state_flags
peer state flags
struct xcl_mailbox_bitstream_kaddr

MAILBOX_REQ_LOAD_XCLBIN_KADDR payload type

Definition

struct xcl_mailbox_bitstream_kaddr {
  uint64_t addr;
};

Members

addr
pointer to xclbin body
struct xcl_mailbox_clock_freqscaling

MAILBOX_REQ_RECLOCK payload type

Definition

struct xcl_mailbox_clock_freqscaling {
  unsigned int region;
  unsigned short target_freqs;
};

Members

region
region of clock
target_freqs
array of target clock frequencies (max clocks: 16)
struct xcl_mailbox_req

mailbox request message header

Definition

struct xcl_mailbox_req {
  uint64_t flags;
  enum xcl_mailbox_request req;
  char data;
};

Members

flags
flags of this message
req
opcode
data
payload of variable length
struct xcl_sw_chan

mailbox software channel message metadata. This defines the interface between daemons (MPD and MSD) and mailbox’s read or write callbacks. A mailbox message (either a request or response) is wrapped by this data structure as payload. A sw_chan is passed between mailbox driver and daemon via read / write driver callbacks. And it is also passed between MPD and MSD via vendor defined interface (TCP socket, etc).

Definition

struct xcl_sw_chan {
  uint64_t sz;
  uint64_t flags;
  uint64_t id;
  char data;
};

Members

sz
payload size
flags
flags of this message as in struct mailbox_req
id
message ID
data
payload (struct mailbox_req or response data matching the request)
struct xcl_mailbox_p2p_bar_addr

Definition

struct xcl_mailbox_p2p_bar_addr {
};

Members