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

XCL_MAILBOX_REQ_SDR_DATA

undescribed

XCL_MAILBOX_REQ_LOAD_XCLBIN_SLOT_KADDR

download xclbin (pointed to by a pointer) to a specific slot (PS/PL)

XCL_MAILBOX_REQ_LOAD_SLOT_XCLBIN

download xclbin (bitstream is in payload) to a specific slot (PS/PL)

XCL_MAILBOX_REQ_MAX

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

XCL_SDR_BDINFO

undescribed

XCL_SDR_TEMP

undescribed

XCL_SDR_VOLTAGE

undescribed

XCL_SDR_CURRENT

undescribed

XCL_SDR_POWER

undescribed

XCL_MULTISLOT_VERSION

undescribed

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_multislot_info

Data structure used to fetch multislot version

Definition

struct xcl_multislot_info {
};

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 {
  int32_t kind;
  uint64_t size;
};

Members

kind

data group (enum xcl_group_kind)

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;
  int8_t 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_slot_kaddr

MAILBOX_REQ_LOAD_XCLBIN_SLOT_KADDR payload type to pass slot information

Definition

struct xcl_mailbox_bitstream_slot_kaddr {
  uint64_t addr;
  uint32_t slot_idx;
};

Members

addr

pointer to xclbin body

slot_idx

Target slot index

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_bitstream_slot_xclbin

MAILBOX_REQ_LOAD_SLOT_XCLBIN payload type

Definition

struct xcl_mailbox_bitstream_slot_xclbin {
  uint32_t slot_idx;
};

Members

slot_idx

Target slot index

struct xcl_mailbox_clock_freqscaling

MAILBOX_REQ_RECLOCK payload type

Definition

struct xcl_mailbox_clock_freqscaling {
  uint32_t region;
  uint16_t 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;
  int32_t req;
  int32_t data;
};

Members

flags

flags of this message

req

opcode (enum xcl_mailbox_request)

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;
  uint64_t 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