mem --read - 2021.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID

UG1393

Release Date

2022-03-29

Version

2021.2 English

Important: This option cannot be used with embedded processor platforms.

The mem --read command reads the indicated number of bytes starting at a specified memory address and writes the contents into an output file.

It has the following command line format:

xbutil mem --read [-d card] [-a [0x]start_addr] 
[-i size_bytes] [-o output filename]

The following table lists the available options.

Table 1. xbutil mem --read Command Options
Option	Description	Required
`-d <card>`	Specifies the target card. <card> can be specified as either the card_id or Bus:Device:Function (BDF). Defaults to card_id = 0 if not specified. Note: Use the `xbutil scan` command to display both the card_id and BDF for installed cards.	N
`-a <start_addr>`	Specifies a valid starting address in either hex or decimal format. Hex format requires leading `0x` that is, `0x100`. Default address is `0x0`. Valid addresses can be obtained using the Linux `dmesg` command as outlined below.	N
`-i <size_bytes>`	Specifies the memory transfer size in bytes in either hex or decimal format. Hex format requires leading `0x` that is, `0x100`. Default size is `0x20000`.	N
`-o <output_file_name>`	Output file name. Default output file is memread.out if output file name not specified.	N

An example of the output using the following command with xclbin using DDR banks 0, 1, 2, and 3 shown below:

xbutil mem --read -a 0x0 -d2 -i 0x10

INFO: Found total 3 card(s), 3 are usable
INFO: Reading from single bank, 256 bytes from DDR/HBM/PLRAM address 0x4000000000
INFO: Read size 0x100 B. Total Read so far 0x100
INFO: Read data saved in file: memread.out; Num of bytes: 256 bytes
INFO: xbutil mem succeeded.

An example of the content of the file generated with the above command is given below. The Linux hex dump command xxd was used to display the file.

00000000: 3d3d 3d3d 5354 4152 5420 6f66 2044 4452  ====START of DDR
00000010: 2044 6174 613d 3d3d 3d3d 3d3d 3d3d 0a00   Data=========..
00000020: 4141 4141 4141 4141 4141 4141 4141 4141  AAAAAAAAAAAAAAAA
00000030: 0a3d 3d3d 3d3d 454e 4420 6f66 2044 4452  .=====END of DDR
00000040: 2044 6174 613d 3d3d 3d3d 3d3d 3d3d 0a00   Data=========..

The following error is returned if an invalid starting address is used. The starting address must be within the address space of the device. In this example 0x400 is an invalid starting address:

ERROR: Start address 0x400 is not valid
Available memory banks:
ERROR: xbutil mem failed.

Tip: Use grep to display the available address spaces. For instance, the following command displays the DDR memory base addresses:

dmesg | grep -A 10 -i ddr

The Linux dmesg output will give the base address for the various DDR memories. A sample of the output for DDR[1] is shown below:

[23174.283512] xocl 0000:a6:00.1: xocl_init_mem: Memory Bank: DDR[1]
[23174.283514] xocl 0000:a6:00.1: xocl_init_mem: Base Address:0x8000000000
[23174.283515] xocl 0000:a6:00.1: xocl_init_mem: Size:0x400000000

Replace the -i ddr search term above with the -i hbm to look up the base address for HBM memories.

To write a known byte pattern, see mem --write.