Supported PS9 API - 3.4 English

Versal Adaptive SoC CPM Mode for PCI Express Product Guide (PG346)

Document ID
PG346
Release Date
2024-05-30
Version
3.4 English

The following are the APIs supported by PS VIP:

Table 1. Supported PS9 API
APIs Inputs Outputs

write_data

Initiate a WRITE transaction (transfer size<= 16 bytes) on one of the AXI-Master ports. This calls the AXI VIP API. This task returns write response when the write transaction is completed.

Example: `TOP.versal_cips_ps_bfm.write_data("R5_API",44'hFFFC_0000, 4, data,response);

[1023:0] master_name: R5_API

[43:0] start_addr: Write address

[4:0] wr_size: Number of bytes to be written.

Valid Write Sizes are:

  • 0x4: 4 Bytes
  • 0x8: 8 Bytes
  • 0xC: 12 Bytes
  • 0x10: 16 Bytes
Note: Transfer should not cross the 16-byte boundary.

[127:0] w_data: Data to be written

[1:0] response: The slave write response from the following:

[OKAY, EXOKAY, SLVERR, DECERR]

read_data

Initiate a READ transaction (transfer size<= 16 bytes) on one of the AXI-Master ports. This calls the AXI VIP API. This task returns data and response when the read transaction is completed.

Example: `TOP.everest_bfm.read_data("R5_API",44'hFFFC_0000, 4, data, response);

[1023:0] master_name: R5_API

[43:0] start_addr: Read address

[4:0] rd_size: Number of bytes to be read

Valid Read Sizes are:

  • 0x4: 4 Bytes
  • 0x8: 8 Bytes
  • 0xC: 12 Bytes
  • 0x10: 16 Bytes
Note: Transfer should not cross the 16-byte boundary.

[127:0] rd_data: Valid Data from the slave

[1:0] response: The slave read response from the following:

[OKAY, EXOKAY, SLVERR, DECERR]

write_data_32

Initiate a WRITE transaction of 4 bytes on one of the AXI-Master ports. This calls the AXI VIP API. This task returns write response when the write transaction is completed.

Example: `TOP.versal_cips_ps_bfm.write_data_32("R5_API",44'hFFFC_0000, data,response);

[1023:0] master_name: R5_API

[43:0] start_addr: write address

[31:0] w_data: Data to be written

[1:0] response: The slavevwrite response from the following:

[OKAY, EXOKAY, SLVERR, DECERR]

write_data_64

Initiate a WRITE transaction of 8 bytes on one of the AXI-Master ports. This calls the AXI VIP API. This task returns write response when the write transaction is completed.

Example: `TOP.versal_cips_ps_bfm.write_data_64("R5_API",44'hFFFC_0000, data,response);

[1023:0] master_name: R5_API

[43:0] start_addr: write address

[63:0] w_data: Data to be written

[1:0] response: The slave write response from the following:

[OKAY, EXOKAY, SLVERR, DECERR]

read_data_32

Initiate a READ transaction of 4 bytes on one of the AXI-Master ports. This calls the AXI VIP API. This task returns data and response when the read transaction is completed.

Example: `TOP.versal_cips_ps_bfm.read_data_32("R5_API",44'hFFFC_0000, data, response);

[1023:0] master_name: R5_API

[43:0] start_addr: Read address

[31:0] rd_data: Valid Data from the slave

[1:0] response: The slave read response from the following:

[OKAY, EXOKAY, SLVERR, DECERR]

read_data_64

Initiate a READ transaction of 8 bytes on one of the AXI-Master ports. This calls the AXI VIP API. This task returns data and response when the read transaction is completed.

Example: `TOP.versal_cips_ps_bfm.read_data_64("R5_API",44'hFFFC_0000, data, response);

[1023:0] master_name: R5_API

[43:0] start_addr: Read address

[63:0] rd_data: Valid Data from the slave

[1:0] response: The slave read response from the following:

[OKAY, EXOKAY, SLVERR, DECERR]

write_burst

Initiate a single AXI write burst transaction (transfer size<= 128 bytes) on one of the AXI-Master ports. This calls the AXI VIP API. This task returns write response when the write transaction is completed.

Example: `TOP.versal_cips_ps_bfm.write_burst("AFI_API",44'hA000_0000,0, 2, 1, 0, 0, 0, wr_m_data,4 , wrs);

[1023:0] master_name: R5_API

[43:0] start_addr: Write address
  • len: Burst Length
  • siz: Burst Size
  • burst: Burst Type
  • lck: Lock Type 0x0: No lock support
  • cache: Cache Type 0x0: No cache support
  • prot: Protection Type 0x0: No protection support
  • [32767:0] data: Data to be sent
  • datasize: Number of bytes (max 256bytes)

[1:0] response: The slave write response from the following:

[OKAY, EXOKAY, SLVERR, DECERR]

read_burst

Initiate a single AXI read burst transaction (transfer size<= 128 bytes) on one of the AXI-Master ports. This calls the AXI VIP API. This task returns data and response when the read transaction is completed.

Example: `TOP.versal_cips_ps_bfm.read_burst("AFI_API",44'hA000_0000,0,2,1,0,0,0,rd_m_data,rresp);

[1023:0] master_name: R5_API

[43:0] start_addr: Read address
  • len: Burst Length
  • siz: Burst Size
  • burst: Burst Type
  • lck: Lock Type 0x0: No lock support
  • cache: Cache Type 0x0: No cache support
  • prot: Protection Type 0x0: No protection support

[32767:0] rd_data: Valid Data from the slave

[1:0] response: The slave Read response from the following:

[OKAY, EXOKAY, SLVERR, DECERR]

write_from_file

Initiate an AXI write transaction on one of the AXI-Master ports. The write data is used from the file. Burst type used is INCR. This is a blocking task and returns only after the completion of AXI WRITE transaction. Need to pass FILE_DATA_WIDTH_128 for accessing files with 128-bit data contents.

If FILE_DATA_WIDTH_128 is passed, then the address must be 128-bit aligned.

If FILE_DATA_WIDTH_128 is not passed, then the address must be 32-bit aligned.

Example: `TOP.versal_cips_ps_bfm.write_from_file("R5_API","write_mgp.txt",40'h8000_0000,4,wrs)

[1023:0] master_name: R5_API

[1023:0] File_name: File name that stores the write data

[43:0] start_addr: write address

[31:0] wr_size: number of bytes to be written

For 32-bit file contents, wr_size should be in mulitples of 4

For 128-bit file contents, wr_size should be in multiples of 16

[1:0] response: The slave write response from the following:

[OKAY, EXOKAY, SLVERR, DECERR]

read_to_file

Initiate an AXI read transaction on one of the AXI-Master ports. The read data is written to a file. Burst type used is INCR. This is a blocking task and returns only after the completion of AXI READ transaction. Need to pass FILE_DATA_WIDTH_128 for accessing files with 128-bit data contents.

If FILE_DATA_WIDTH_128 is passed, then the address must be 128-bit aligned.

If FILE_DATA_WIDTH_128 is not passed, then the address must be 32-bit aligned.

Example: `TOP.versal_cips_ps_bfm.read_to_file("R5_API","read_mgp0.txt",40'h8000_0000,4,rresp)

[1023:0] master_name: R5_API

[1023:0] file_name: File name that stores the write data

[43:0] start_addr: write address

[31:0] rd_size: number of bytes to be read

For 32-bit file contents, rd_size should be in mulitples of 4

For 128-bit file contents, rd_size should be in multiples of 16

[1:0] response: The slave write response from the following:

[OKAY, EXOKAY, SLVERR, DECERR]

pre_load_mem

Preload OCM with random_data/all_zeros/all_ones. Based on the address and data type specified, the data is loaded in OCM. Address must be 32-bit aligned.

Example: `TOP.versal_cips_ps_bfm.pre_load_mem(2'b10,44'hFFFF_0000,4);

[1:0] data_type: Random, zeros or ones

  • l00/11 – Random
  • 01 – Zeros
  • 10 – Ones

[43:0] start_addr: Start Address from where OCM should be initialized with the data

[31:0] no_of_bytes: Number of data bytes to be loaded

None

pre_load_mem_from_file

Preload OCM with data from a file. Based on the address specified, the data is loaded in OCM.

Example: `TOP.versal_cips_ps_bfm.pre_load_mem_from_file("preload_ocm.txt",addr1,no_bytes_transfer_ocm);

[1023:0] file_name: File name (max. 256 characters)

[43:0] start_addr: Start Address from where OCM should be initialized with data from the file

[31:0] Num lines: Number of lines (each row should match 32 bits)

None

peek_mem_to_file

This reads from the OCM and prints to a file.

Example: `TOP.versal_cips_ps_bfm.peek_mem_to_file(“read_ocm_test_sanity.txt"},addr1,no_of_bytes);

[1023:0] file_name: File name (max. 128 characters; Read data is written to this file)

[43:0] start_addr: Start Address to read the data from

[31:0] no_of_bytes: Number of data bytes to be read

None

write_mem

Back door write to the OCM memory. Based on the address specified, the data is written to OCM. Address must be 32-bit aligned.

Example: `TOP.versal_cips_ps_bfm.write_mem(data,40'hFFFF_2000, no_of_bytes);

[8191:0] data: Write data to be written to memory

[43:0] start_addr: Start Address to write the data from

[15:0] no_of_bytes: Number of data bytes to be write (max. 128 bytes)

None

read_mem

Back door read from the OCM memory. Based on the address specified, the data is read from OCM.

Example: `TOP.versal_cips_ps_bfm.read_mem(40'hFFFF_4000, 128, rd_m_data);

[43:0] start_addr: Start Address to read the data from

[15:0] no_of_bytes: Number of data bytes to be read

[8191:0] data: read data from memory.

por_reset

Soft reset for VIP. It is a mandatory reset. It's Active Low reset.

Example: `TOP.versal_cips_ps_bfm.por_reset(1) → De-asserts the BFM's reset

`TOP.versal_cips_ps_bfm.por_reset(0) → Asserts the BFM's reset

por_reset_ctrl: 1-bit input reset to VIP. por_reset_ctrl is active-Low input

None

pl_gen_reset

This API will assert the PS to PL resets.

Example: `TOP.versal_cips_ps_bfm.pl_gen_reset(4'hE) → De-asserts the PLRST1N, PLRST2N and PLRST3N.

→ Asserts the PLRST0N

[3:0] reset_ctrl

Depending on the reset_ctrl value, one of the reset is asserted. reset_ctrl is Active Low input.

Example:

  • reset_ctrl: 4’hE, PLRST0N is asserted
  • reset_ctrl: 4’hD, PLRST1N is asserted
  • reset_ctrl: 4’hB, PLRST2N is asserted
  • reset_ctrl: 4’h7, PLRST3N is asserted

Any combination of above is also possible.

reset_ctrl: 4’h3, PLRST2N, PLRST3N are asserted

None

pl_gen_clock

This API generates the PS to PL clocks with the frequency in MHz as the input along with the clock port number.

Example: `TOP.versal_cips_ps_bfm.pl_gen_clock(0,100) → Generates PMCRCLKCLK[0] with 100Mhz frequency

[1:0] clk_num: 2’b00 -> PMCRCLKCLK[0]

  • 2’b01 -> PMCRCLKCLK[1]
  • 2’b10 -> PMCRCLKCLK[2]
  • 2’b11 -> PMCRCLKCLK[3]

[31:0] freq_in_mhz: This can be any integer value

None

read_interrupt

Use this API to poll the interrupt status at any given time. This is a non-blocking task to poll the interrupt status and returns immediately with current state on interrupt lines.

Example: `TOP.versal_cips_ps_bfm.read_interrupt()

It returns the interrupt status (16-bit) for {PLPSIRQ1,PLPSIRQ0}.

None

[15:0] irq_status: Interrupts generated by PL.

wait_interrupt

Use this API to wait for any of the interrupt to occur. This is a blocking task to wait for an interrupt to occur and returns immediately with any of the four interrupt lines asserts.

Example: `TOP.versal_cips_ps_bfm.wait_interrupt(4)
  • Above call waits for an interrupt on PLPSIRQ0[2]
  • It also returns the interrupt status (16-bit) for {PLPSIRQ1,PLPSIRQ0}.

Example: `TOP.versal_cips_ps_bfm.wait_interrupt(14)

  • Above call waits for an interrupt on PLPSIRQ1[6]
  • It also returns the interrupt status (16-bit) for {PLPSIRQ1,PLPSIRQ0}

[3:0] irq: Interrupt line number

  • irq: 0 → PLPSIRQ0[0], 1 → PLPSIRQ0[1], 2 → PLPSIRQ0[2],
  • 3 → PLPSIRQ0[3], 4 → PLPSIRQ0[4], 5 → PLPSIRQ0[5],
  • 6 → PLPSIRQ0[6], 7 → PLPSIRQ0[7,
  • 8 → PLPSIRQ1[0], 9 → PLPSIRQ1[1], 10 → PLPSIRQ1[2],
  • 1 → PLPSIRQ1[3], 12 → PLPSIRQ0[4], 13 → PLPSIRQ0[5],
  • 14 → PLPSIRQ1[6], 15 → PLPSIRQ1[7].

[15:0] irq_status: Interrupts generated by PL.

irq_status = {PLPSIRQ1[7:0] ,PLPSIRQ0[7:0]}.

trigger_interrupt

Use this API to trigger an interrupt pin (IRQFPD/IRQLDP/IRQPMC) of the PL. This is a non blocking task for triggering the interrupts.

Example: `TOP.versal_cips_ps_bfm.trigger_interrupt(1,10)

[1:0] intr_type: To specify either IRQFPD/TRQLPD/IRQPMC

01: IRQFPD, 10: IRQLPD, 11: IRQPMC

[7:0] interrupt_no: Interrupt pin number/index of the particular index type

Example: If, intr_type: 10, interrupt_no : 32

Then, IRQLPD[32] is triggered.

None

clear_interrupt

Use this API to clear an interrupt pin (IRQFPD/IRQLDP/IRQPMC) of the PL. This is a non blocking task for clearing the interrupts.

Example: `TOP.versal_cips_ps_bfm.clear_interrupt(1,10)

[1:0] intr_type: To specify either IRQFPD/TRQLPD/IRQPMC

01: IRQFPD, 10: IRQLPD, 11: IRQPMC

[7:0] interrupt_no: Interrupt pin number/index of the particular index type

Example: If, intr_type: 10, interrupt_no : 32

Then, IRQLPD[32] is cleared

None

read_register

This API call is for reading a 32-bit register value.

Example: `TOP.versal_cips_ps_bfm.read_register(32'hFFA80000)

[31:0] addr: Register address [31:0] DATA: Valid register read data

select_cci_boundary

This API can be used to select the CCI address boundary to be either 4K/2K/1K.

Example: `TOP.versal_cips_ps_bfm.select_cci_boundary(0)

[1:0] cci_boundary

2’b00: 4K

2’b01: 2K

2’b10: 1K

2’b11: Undefined

By default, it is 4K

None

fatal_to_warning

This API is used to convert the FATAL messages reported for the components R5_API, OCM and REG space.

Example: `TOP.versal_cips_ps_bfm.fatal_to_warning("R5_API")

[1023:0] component_name

Permitted component names are:

  • R5_API
  • OCM
  • REG
None

set_routing_config

This API is used to provide the routing information inside the PS VIP. It also prints the entire routing information configured.

Example: `TOP.versal_cips_ps_bfm.set_routing_config("R5_API","OCM",1)

Above API call enables the routing from R5_API to OCM

`TOP.versal_cips_ps_bfm.set_routing_config("R5_API","OCM",0)

Above API call disables the routing from R5_API to OCM

[8191:0] source_port_name: Incoming ports of PS CIPS VIP

Supported source port names:

  • S_AXI_FPD
  • S_AXI_GP2
  • S_AXI_LPD
  • NOC_FPD_CCI_0
  • NOC_FPD_CCI_1
  • NOC_FPD_AXI_0
  • NOC_FPD_AXI_1
  • S_ACP_FPD
  • S_ACE_FPD
  • NOC_PMC_AXI_0
  • NOCPSPCIAXI0
  • A72_API
  • NOC_API
  • R5_API
  • CPMPSAXI0
  • CPMPSAXI1

[8191:0] destination_port_name: Outgoing ports from the PS CIPS VIP

Supported destination port names:

  • FPD_CCI_NOC
  • M_AXI_FPD
  • M_AXI_LPD
  • FPD_AXI_NOC_0
  • FPD_AXI_NOC_1
  • PSNOCPCIAXI0
  • PSNOCPCIAXI1
  • PMC_NOC_AXI_0
  • NOC_LPD_AXI_0
  • PSCPMPCIEAXI
  • OCM
  • REG
  • PSCPMCFG

routing_en:

  • 1: Enables routing for the specified path
  • 0: Disables routing for the specified path
None

get_routing_config

This API call is used to print the configured routing information.

Example: `TOP.versal_cips_ps_bfm.get_routing_config();

None None

cfg_slverr_address_range

This API call sets an address range for which SLVERR response is expected. This API can be called multiple times for multiple such address ranges.

It also prints all the configured SLVERR address ranges.

Example: `TOP.versal_cips_ps_bfm.cfg_slverr_address_range('hFFFC_0204,'hFFFC_0204,1);

[63:0] slverr_start_address

[63:0] slverr_end_address

set_slv_error

  • 0: SLVERR for the programmed range is disabled
  • 1: SLVERR for the programmed range is enabled
None

write_register

This API is for performing back door register write.

`TOP.versal_cips_ps_bfm.write_register(32'gFFA80000,32'hAAAAAAAA,4);

[31:0] addr : Register address

[31:0] data : Data to be written to the register

int size : Number of bytes to be written. Possible values are 1,2,3 and 4 only.

None