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

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