quickstart corrections and adjust to macOS

JIRA CI-264

quickstart/README.md

@@ -1,6 +1,8 @@
 # Running system on targets
 
-This chapter presents how to run Phoenix-RTOS on supported targets. It is assumed that `phoenix-rtos-project` is built and building artifacts are available in the `_boot` directory. The building process has been described in [phoenix-rtos-doc/building](../building/README.md).
+This chapter presents how to run Phoenix-RTOS on supported targets. It is assumed that `phoenix-rtos-project`
+is built, and building artifacts are available in the `_boot` directory. The building process has been described
+in [phoenix-rtos-doc/building](../building/README.md).
 
 ## See also
 

quickstart/armv7a9-zynq7000-qemu.md

@@ -1,7 +1,9 @@
 # Running system on `armv7a9-zynq7000-qemu` (Xilinx Zynq-7000, qemu emulator)
 
-These instructions describe how to run a Phoenix-RTOS system image for the `armv7a9-zynq7000-qemu` target architecture using docker.
-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-qemu` target.
+These instructions describe how to run a Phoenix-RTOS system image for the `armv7a9-zynq7000-qemu` target
+architecture using docker.
+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-qemu` target.
 
 See [how to build the Phoenix-RTOS system image](../building/README.md).
 
@@ -12,56 +14,56 @@ Firstly, you need to have the docker installed.
   <details>
   <summary>How to get docker (Ubuntu 20.04)</summary>
 
-  - Install required packages
+  Install required packages
 
-  ```
+  ```bash
   sudo apt-get update && \
   sudo apt-get install curl \
   ca-certificates \
   gnupg \
   lsb-release
   ```
 
-  - Make docker packages available
+  Make docker packages available
 
-  ```
+  ```bash
   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg && \
   echo \
   "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   ```
 
-  - Install docker packages
+  Install docker packages
 
-  ```
+  ```bash
   sudo apt-get update && \
   sudo apt-get install docker-ce docker-ce-cli containerd.io
   ```
 
-  - Check if Docker is properly installed (version can be different):
+  Check if Docker is properly installed (version can be different):
 
-  ```
+  ```bash
   sudo docker --version
   ```
 
   <img src="_images/docker-version.png" width="700px">
 
-  - To make calling docker command without `sudo` possible type:
+  To make calling docker command without `sudo` possible type:
 
-  ```
+  ```bash
   sudo groupadd docker
   ```
 
   Even if group `docker` already exists type then:
 
-  ```
+  ```bash
   sudo usermod -aG docker $USER && \
   newgrp docker
   ```
 
-  - Check if running docker images without sudo works properly:
+  Check if running docker images without sudo works properly:
 
-  ```
+  ```bash
   docker run hello-world
   ```
 
@@ -71,17 +73,72 @@ Firstly, you need to have the docker installed.
 
   [docker.com](https://docs.docker.com/engine/install/ubuntu/)
 
-  </details> 
+  </details>
 
-Now, with docker installed you can run Phoenix-RTOS using the following command:
+<details>
+  <summary>Installing Docker on macOS</summary>
 
-```
+  You can find the up-to-date instructions at <https://docs.docker.com/desktop/install/mac-install/>
+
+  To make this process simpler below is an example of installation for Mac with the Intel chip:
+
+  Download the installer:
+
+  ```bash
+  curl -o Docker.dmg "https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&amp;utm_medium=webreferral&amp;utm_campaign=docs-driven-download-mac-amd64"
+  ```
+
+  Run the following commands to install Docker:
+
+  ```bash
+  sudo hdiutil attach Docker.dmg && \
+  sudo /Volumes/Docker/Docker.app/Contents/MacOS/install && \
+  sudo hdiutil detach /Volumes/Docker
+  ```
+
+  Then add the path to `docker` binaries to the `PATH` environment variable:
+
+  ```bash
+  export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"
+  ```
+
+  It's recommended to place it in `.zshrc` startup script to export in every time during startup:
+
+  ```bash
+  echo "export PATH=\"/Applications/Docker.app/Contents/Resources/bin:\$PATH\"" >> $HOME/.zshrc
+  ```
+
+  Check if Docker is properly installed by checking version:
+
+  ```bash
+  docker --version
+  ```
+
+  Check if running docker images without sudo works properly:
+
+  ```bash
+  docker run hello-world
+  ```
+
+  *If you see the following error: `ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.` you
+  can try to install `colima` and check once again:
+
+  ```bash
+  brew install colima && \
+  colima start
+  ```
+
+  </details>
+
+Now, with docker installed, you can run Phoenix-RTOS using the following command:
+
+```bash
 ./docker-devel.sh scripts/armv7a9-zynq7000-qemu.sh
 ```
 
 As a result, you should see `psh` (Phoenix-RTOS shell).
 
- - Note: It may take a while.
+- Note: It may take a while.
 
 <img src="_images/zynq7000-emu-start.png" width="700px">
 
@@ -90,15 +147,15 @@ As a result, you should see `psh` (Phoenix-RTOS shell).
 
   All necessary tools including qemu are provided in phoenixrtos/devel docker image (run by `docker-devel.sh` script)
 
-  If you want, you can read more about docker containerization on https://www.docker.com/resources/what-container
+  If you want, you can read more about docker containerization at <https://www.docker.com/resources/what-container>
 
-  </details> 
+  </details>
 
 ## Using Phoenix-RTOS
 
 To get the available command list please type:
 
-```
+```bash
 help
 ```
 

quickstart/armv7a9-zynq7000-zedboard.md

@@ -52,19 +52,27 @@ The onboard UART-USB converter is used here.
 
 - Now you should verify, what USB device on your host-pc is connected with the `UART` (console). To check that run:
 
+  - On Ubuntu:
+
   ```bash
   ls -l /dev/serial/by-id
   ```
 
   <img src="_images/zynq7000-ls.png" width="700px">
 
-  If your output is like in the screenshot above, the console (`UART` in the evaluation board) is on the `ACM0` port.
+  - On macOS:
+
+  ```bash
+  ls -l /dev/tty.*
+  ```
+
+  <img src="_images/zynq7000-ls-mac.png" width="700px">
 
 - When the board is connected to your host-pc,
  open serial port in terminal using picocom and type the console port (in this case ACM0)
 
   ```bash
-  picocom -b 115200 --imap lfcrlf /dev/ttyACM0
+  picocom -b 115200 --imap lfcrlf /dev/tty<port>
   ```
 
   <details>
@@ -81,6 +89,16 @@ The onboard UART-USB converter is used here.
   sudo usermod -a -G tty <yourname>
   ```
 
+  </details>
+
+  <details>
+  <summary>How to get picocom (macOS)</summary>
+
+  ```bash
+  brew update &&\
+  brew install picocom
+  ```
+
   </details>
   </br>
 
@@ -140,21 +158,31 @@ Please wait until erasing is finished.
 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:
 
+- On Ubuntu:
+
 ```plaintext
 ls -l /dev/serial/by-id
 ```
 
 <img src="_images/zynq7000-ls-2.png" width="700px">
 
+- On macOS:
+
+```bash
+ls -l /dev/tty.*
+```
+
+<img src="_images/zynq7000-ls2-mac.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, ttyACM1):
+ (choose suitable device):
 
 ```plaintext
 cd _boot/armv7a9-zynq7000-zedboard
 ```
 
 ```plaintext
-sudo ./phoenixd -p /dev/ttyACM1 -b 115200 -s .
+sudo ./phoenixd -p /dev/tty<port> -b 115200 -s .
 ```
 
 <img src="_images/zynq7000-phoenixd.png" width="700px">
@@ -186,16 +214,26 @@ To run it you should follow the steps below:
 
 - Check which port the console appeared on:
 
+  - On Ubuntu:
+  
   ```bash
   ls -l /dev/serial/by-id/
   ```
 
   <img src="_images/zynq7000-ls-3.png" width="700px">
+  
+  - On macOS:
+
+  ```bash
+  ls -l /dev/tty.*
+  ```
+
+  <img src="_images/zynq7000-ls-mac.png" width="700px">
 
 - connect to that port:
 
   ```bash
-  picocom -b 115200 --imap lfcrlf /dev/ttyACM0
+  picocom -b 115200 --imap lfcrlf /dev/tty<port>
   ```
 
 - restart the chip using the `PS-RST` button to print initialization logs:

quickstart/armv7a9-zynq7000.md

@@ -1,23 +1,32 @@
 # Running system on `armv7a9-zynq7000` (Xilinx Zynq-7000)
 
-This version is designed for Xilinx Zynq-7000 SoC (System on Chip) with ARM Cortex-A9 core. To launch this version the final disk image should be provided. The image is created as the final artifact of the `phoenix-rtos-project` building and is located in the `_boot` directory. The disk image consists of the bootloader (plo), kernel, UART driver (tty), dummyfs filesystem server (RAM disk), flash driver with jffs file system and psh (shell). Necessary tools to carry out the flashing process are located in the `_boot` directory as well.
+This version is designed for Xilinx Zynq-7000 SoC (System on Chip) with ARM Cortex-A9 core. To launch this
+version the final disk image should be provided. The image is created as the final artifact of the
+`phoenix-rtos-project` building and is located in the `_boot` directory. The disk image consists
+of the bootloader (plo), kernel, UART driver (tty), dummyfs filesystem server (RAM disk), flash driver with
+jffs file system and psh (shell). Necessary tools to carry out the flashing process are located
+in the `_boot` directory as well.
 
 ## Development board or emulator
 
-The easiest way to start programming hardware targets using Phoenix-RTOS is to get some of the evaluation boards with a specified target processor or microcontroller. In this case [ZedBoard](https://www.xilinx.com/products/boards-and-kits/1-8dyf-11.html) is the example of a board with the `zynq7000` SoC, where the default configuration of peripherals allows to run Phoenix-RTOS.
+The easiest way to start programming hardware targets using Phoenix-RTOS is to get some of the evaluation
+boards with a specified target processor or microcontroller. In this case,
+[ZedBoard](https://www.xilinx.com/products/boards-and-kits/1-8dyf-11.html) is an example of a board with
+the `zynq7000` SoC, where the default configuration of peripherals allows running Phoenix-RTOS.
 The next steps for a development board are described below.
 
 - [Running system on `armv7a9-zynq7000-zedboard`](armv7a9-zynq7000-zedboard.md)
 
-If you don't have one, you can check the running system for this target architecture on an emulator and follow the steps from the site below.
+If you don't have one, you can check the running system for this target architecture on an emulator and follow
+the steps from the site below.
 
 - [Running system on `armv7a9-zynq7000-qemu`](armv7a9-zynq7000-qemu.md)
 
 ## Common problems on zynq7000 boards
 
 - Phoenix-RTOS loader does not appear:
   - When booting using SD card: Make sure that a proper `BOOT.bin` file
-  is placed on the card, and it's in a binary format (right click -> properties):
+  is placed on the card, and that it's in a binary format (right click -> properties):
 
       <img src="_images/zynq7000-problems-file-type.png" width="400px">