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