quickstart: add armv7a9-zynq7000-zturn quickstart doc

JIRA: CI-174

quickstart/armv7a9-zynq7000-zturn.md

@@ -0,0 +1,215 @@
+# Running system on `armv7a9-zynq7000-zturn` (Xilinx Zynq-7000, Zturn development board)
+
+These instructions describe how to run a Phoenix-RTOS system image for `armv7a9-zynq7000-zturn` target architecture.
+Note that, the build artifacts, including the system image, should be first provided in the `_boot` directory.
+If you haven't run the `build.sh` script yet, run it for `armv7a9-zynq7000-zturn` target.
+
+See [how to build the Phoenix-RTOS system image](../building/README.md).
+
+## Preparing the board
+
+Preparing the board depends on how the plo is loaded into RAM, this quickstart describe 2 approaches - loading from SD
+card and NAND flash, depending on your needs use one of them. For example if you have empty flash memory or want to
+load new plo use SD card, otherwise you can simply load plo from NAND flash.
+
+### Load plo form SD card
+
+- Firstly, prepare SD card, I would prefer to format it to FAT32
+
+- Secondly, you should copy the disk image `phoenix.disk` from the `_boot/armv7a9-zynq7000-zturn` directory to the SD
+card and rename it to `BOOT.bin`, make sure that this file is in binary format, otherwise you won't be able to load
+plo (Phoenix-RTOS Loader) from SD card to RAM.
+
+- Then, insert the SD card into the board.
+
+- To allow load from SD card, set the jumpers to the following configuration:
+
+  <img src="_images/zynq7000-zturn-sd-boot.jpg" width="400px">
+
+### Load plo from NAND flash
+
+- To allow load from NAND flash, set the jumpers to the following configuration:
+
+  <img src="_images/zynq7000-zturn-flash-boot.jpg" width="400px">
+
+### Next steps are common for both approaches
+
+- To communicate with the board you will need to connect the USB cable to the `USB_UART` port (`J6`).
+
+- You should also connect another micro USB cable to the `USB_OTG` port (`J2`).
+
+  The picture below presents how the board should be connected:
+
+  <img src="_images/zynq7000-zturn-connections.jpg" width="700px">
+
+- If you connected everything like in the picture above, the board should be powered on and the `D25` POWER LED should bright blue.
+
+- Now you should verify, what USB device on your host-pc is connected with the `UART` (console). To check that run:
+
+  ```
+  ls -l /dev/serial/by-id
+  ```
+
+  <img src="_images/zynq7000-zturn-ls.png" width="700px">
+
+  If your output is like in the screenshot above, the console (`UART` in the evaluation board) is on the `USB0` port.
+
+- When the board is connected to your host-pc, open serial port in terminal using picocom and type the console port
+ (in this case USB0)
+
+  ```
+  picocom -b 115200 --imap lfcrlf /dev/ttyACM0
+  ```
+
+  To use picocom without sudo privileges run this command and then restart:
+
+  ```
+  sudo usermod -a -G tty <yourname>
+  ```
+
+- You should see such output:
+
+  <img src="_images/zynq7000-zturn-picocom.png" width="700px">
+
+  <details>
+  <summary>How to get picocom (Ubuntu 20.04)</summary>
+
+  ```
+  sudo apt-get update && \
+  sudo apt-get install picocom
+  ```
+
+  </details>
+  </br>
+
+You can leave the terminal with the serial port open, and follow the next steps.
+
+## Flashing the Phoenix-RTOS system image
+
+At first before any flashing, you need to enter Phoenix-RTOS loader (plo).
+
+### Entering Phoenix-RTOS loader (plo)
+
+Press RESET button (`K2`) to restart the chip.
+
+If flash memory doesn't contain system image, booting process will stop at plo level, you shoud see:
+
+<img src="_images/zynq7000-zturn-magic.png" width="400px">
+
+This error just says that no system image is on the flash, just plo.
+
+Otherwise, in order to get into plo you need to press any key within 500ms. If you don't do that, plo will load system
+and start psh, but we cannot flash from there. Output when you enter psh:
+
+<img src="_images/zynq7000-zturn-psh.png" width="700px">
+
+Restart the chip with RESTART button `K2` and try again. Output of successful enter to plo:
+
+<img src="_images/zynq7000-zturn-plo.png" width="700px">
+
+If you want to flash the system image please follow the next steps.
+
+### Copying image to flash memory using PHFS (phoenixd)
+
+To flash the disk image, first, you need to verify on which port plo USB device has appeared. You can check that using `ls` as follow:
+
+```bash
+ls -l /dev/serial/by-id
+```
+
+<img src="_images/zynq7000-ls-2.png" width="700px">
+
+To share disk image to the bootloader, `phoenixd` has to be launched with the following arguments (choose suitable
+ttyACMx device, in this case, ttyACM0):
+
+```
+cd _boot/armv7a9-zynq7000-zturn
+```
+
+```bash
+sudo ./phoenixd -p /dev/ttyACM0 -b 115200 -s .
+```
+
+<img src="_images/zynq7000-phoenixd.png" width="700px">
+
+Before flashing, you should use erase command.
+
+```bash
+erase flash0 0x0 0x1000000
+```
+
+To start copying the file, write the following command in the console with plo interface:
+
+```bash
+copy usb0 phoenix.disk flash0 0x0 0x0
+```
+
+<img src="_images/zynq7000-plo-copy.png" width="700px">
+
+### Booting Phoenix-RTOS from NAND flash memory
+
+Now, the image is located in the NAND Flash memory.
+To run it you should follow the steps below:
+
+- Power off the board by disconnecting USB_OTG and USB_UART connectors
+
+- Change jumpers position as follows:
+
+  <img src="_images/zynq7000-zturn-flash-boot.jpg" width="400px">
+
+- Power on the board by connecting USB_OTG and USB_UART connectors
+
+- Check which port the console appeared on:
+
+  ```
+  ls -l /dev/serial/by-id/
+  ```
+
+  <img src="_images/zynq7000-ls-3.png" width="700px">
+
+- connect to that port:
+
+  ```
+  picocom -b 115200 --imap lfcrlf /dev/ttyACM0
+  ```
+
+- restart the chip using the `K2` RESET button, after that booting starts
+
+- after successful boot you should see:
+
+  <img src="_images/zynq7000-qspi-start.png" width="700px">
+
+Psh prompt indicate that everything is up and running.
+
+## Using Phoenix-RTOS
+
+To get the available command list please type:
+
+```
+help
+```
+
+<img src="_images/zynq7000-help.png" width="700px">
+
+If you want to get the list of working processes please type:
+
+```bash
+ps
+```
+
+<img src="_images/zynq7000-ps.png" width="700px">
+
+To get the table of processes please type:
+
+```bash
+top
+```
+
+<img src="_images/zynq7000-top.png" width="700px">
+
+## See also
+
+1. [Running system on armv7a9-zynq7000](armv7a9-zynq7000.md)
+2. [Running system on armv7a9-zynq7000 on emulator](armv7a9-zynq7000-emu.md)
+3. [Running system on targets](README.md)
+4. [Table of Contents](../README.md)