1.. zephyr:board:: kv260_r5
2
3Overview
4********
5This configuration provides support for the RPU, real-time processing unit on Xilinx
6KV260 development board, it can operate as following:
7
8* Two independent R5 cores with their own TCMs (tightly coupled memories)
9* Or as a single dual lock step unit with double the TCM size.
10
11This processing unit is based on an ARM Cortex-R5 CPU, it also enables the following devices:
12
13* ARM PL-390 Generic Interrupt Controller
14* Xilinx Zynq TTC (Cadence TTC)
15* Xilinx Zynq UART
16
17Hardware
18********
19Supported Features
20==================
21
22The following hardware features are supported:
23
24+--------------+------------+----------------------+
25| Interface    | Controller | Driver/Component     |
26+==============+============+======================+
27| GIC          | on-chip    | generic interrupt    |
28|              |            | controller           |
29+--------------+------------+----------------------+
30| TTC          | on-chip    | system timer         |
31+--------------+------------+----------------------+
32| UART         | on-chip    | serial port          |
33+--------------+------------+----------------------+
34
35The kernel currently does not support other hardware features on this platform.
36
37Devices
38========
39System Timer
40------------
41
42This board configuration uses a system timer tick frequency of 1000 Hz.
43
44Serial Port
45-----------
46
47This board configuration uses a single serial communication channel with the
48on-chip UART1.
49
50Memories
51--------
52
53Although Flash, DDR and OCM memory regions are defined in the DTS file,
54all the code plus data of the application will be loaded in the sram0 region,
55which points to the DDR memory. The ocm0 memory area is currently available
56for usage, although nothing is placed there by default.
57
58Known Problems or Limitations
59==============================
60
61The following platform features are unsupported:
62
63* Dual-redundant Core Lock-step (DCLS) execution is not supported yet.
64* Only the first core of the R5 subsystem is supported.
65* Xilinx Zynq TTC driver does not support tickless mode operation.
66* The Cortex-R5 and the Cortex-A53 shares the same UART controller, more details below.
67
68Programming and Debugging
69*************************
70
71Currently the best way to run this sample is by loading it through remoteproc
72from the APU, running Linux, to the RPU, assuming the target board has a compatible
73Linux kernel.
74Users can make use of Xilinx's pre-built Petalinux reference images as a starting point to enable
75remoteproc support, it is based around 5.15 Xilinx maintained kernel, as described here:
76
77https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/1641152513/Kria+K26+SOM#PetaLinux
78
79The other option is to use the reference image from the openAMP project, the link
80below points, betweem the options, to the kv260 target:
81
82https://github.com/OpenAMP/openamp-ci-builds/releases/tag/v2022.12
83
84Select the option ``xilinx-kv260.tar.gz``, and just decompress it to the target rootfs
85partition of user's SD card:
86
87.. code-block:: console
88
89        $ sudo mount /dev/<user-sd> /media/rootfs
90        $ sudo tar -C /media/rootfs -xzf xilinx-kv260.tar.gz
91        $ sudo umount /media/rootfs
92
93Your SD file may be ready for use, just plug it to the slot located in the board.
94
95After getting the Linux image running on the target board, build a Zephyr application,
96such as the hello world sample shown below:
97
98.. zephyr-app-commands::
99   :zephyr-app: samples/hello_world
100   :host-os: unix
101   :board: kv260_r5
102   :goals: build
103
104Due to a hardware limitation, both Linux and Zephyr share the same UART
105controller, meaning when the Zephyr application is started it will takeover the
106console from Linux.
107
108To avoid this limitation when accessing the Linux shell, the best approach is to
109connect to the board using ``ssh`` over the network (not using the FTDI
110USB interface on the board), with the dev board and the host computer
111connected to the same network.
112
113Assuming you are using the default ``petalinux`` user from the Xilinx
114reference image , open a terminal on the host machine and ssh into the
115development board with the board's IP address (found via ``ifconfig``):
116
117.. code-block:: console
118
119        $ ssh petalinux@<board-ip-address>
120
121The initial password should be ``petalinux``. On another terminal deploy
122the Zephyr application ``.elf`` file using utility like the ``scp`` or ``rsync``,
123for example:
124
125.. code-block:: console
126
127        $ scp /path/to/zephyr_app_elf_file  petalinux@<board-ip-address>:/home/petalinux
128
129After that move the file to ``/lib/firmware`` directory, then you be able to start the firmware
130on the desired RPU via remoteproc with:
131
132.. code-block:: console
133
134        $ sudo -i # You need to operate the remoteproc as root
135        $ echo zephyr.elf > /sys/class/remoteproc/remoteproc0/firmware
136        $ echo start > /sys/class/remoteproc/remoteproc0/state
137
138With another terminal connected to UART1 on the host machine
139(available via one of the tty ports with the on-board FTDI chip),
140you should see the Zephyr application running:
141
142.. code-block:: console
143
144        *** Booting Zephyr OS build v3.4.0  ***
145        Hello World kv260_r5!
146
147References
148**********
149
1501. ARMv7-A and ARMv7-R Architecture Reference Manual (ARM DDI 0406C ID051414)
1512. Cortex-R5 and Cortex-R5F Technical Reference Manual (ARM DDI 0460C ID021511)
1523. Zynq UltraScale+ Device Technical Reference Manual (UG1085)
1534. Kria KV260 Vision AI Starter Kit User Guide (UG1089)
154