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).
 
@@ -14,7 +16,7 @@ Firstly, you need to have the docker installed.
 
   - Install required packages
 
-  ```
+  ```bash
   sudo apt-get update && \
   sudo apt-get install curl \
   ca-certificates \
@@ -24,7 +26,7 @@ Firstly, you need to have the docker installed.
 
   - 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 \
@@ -33,35 +35,35 @@ Firstly, you need to have the docker installed.
 
   - 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):
 
-  ```
+  ```bash
   sudo docker --version
   ```
 
   <img src="_images/docker-version.png" width="700px">
 
   - 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:
 
-  ```
+  ```bash
   docker run hello-world
   ```
 
@@ -71,11 +73,65 @@ 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
 ```
 
@@ -90,15 +146,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> 
 
 ## Using Phoenix-RTOS
 
 To get the available command list please type:
 
-```
+```bash
 help
 ```
 

quickstart/armv7a9-zynq7000.md

@@ -1,27 +1,36 @@
 # 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 to run 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">
 
-  - Try to open picocom for a second time (it could got stuck).
+  - Try to open picocom for a second time (it could get stuck).
 
   - Power down a board and try once again (changing boot modes needs restart by power off).
 

quickstart/armv7m4-stm32l4x6-nucleo.md

@@ -1,16 +1,23 @@
 # Running system on `armv7m4-stm32l4x6-nucleo` (ST STM32L4x)
 
-This version is designated for STM32L4x6 processors with Cortex-M4 core. To launch this version the final flash 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 image consists of a kernel, TTY UART driver, RAM disk filesystem, and psh (shell).
+This version is designated for STM32L4x6 processors with Cortex-M4 core. To launch this version the final flash
+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 image consists of a kernel, TTY UART driver, RAM disk filesystem, and
+psh (shell).
 
 See [how to build the Phoenix-RTOS system image](../building/README.md).
 
 ## Development board
 
-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 [NUCLEO-L4A6ZG](https://www.st.com/en/evaluation-tools/nucleo-l4a6zg.html#overview) is the example of a board with `stm32l4x6` microcontroller.
+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,
+[NUCLEO-L4A6ZG](https://www.st.com/en/evaluation-tools/nucleo-l4a6zg.html#overview)
+is an example of a board with a `stm32l4x6` microcontroller.
 
 ## Connecting the board
 
-To provide a power supply for the board and make flashing possible, you have to connect a USB to micro USB cable between your host pc and the development board (`USB PWR` port, also called `CN1`).
+To provide a power supply for the board and make flashing possible, you have to connect a USB to micro USB
+cable between your host pc and the development board (`USB PWR` port, also called `CN1`).
 To communicate with the board you will need to use a UART-USB converter, like `PL2303 TA`.
 
 - Connect TX, RX, and GND wires to the USART2 (called also USART_B) in the Nucleo board.
@@ -21,36 +28,63 @@ To communicate with the board you will need to use a UART-USB converter, like `P
 
   <img src="_images/nucleo-pinout.png" width="400px">
 
-  Source: The Nucleo board's schematic, available on https://www.st.com/en/evaluation-tools/nucleo-l4a6zg.html#cad-resources
+  Source: The Nucleo board's schematic, available on
+  <https://www.st.com/en/evaluation-tools/nucleo-l4a6zg.html#cad-resources>
 
 - Put the converter into your host PC's USB port
 
   The picture below presents how the board should be connected:
 
   <img src="_images/stm32l4x6-connections.png" width="400px">
 
-- Open serial port in terminal using picocom
+- 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
   ```
-  picocom -b 115200 --imap lfcrlf /dev/ttyUSB0
+
+  <img src="_images/stm32l4x6-ls-ubuntu.png" width="700px">
+
+  - On macOS:
+
+  ```bash
+  ls -l /dev/tty.*
+  ```
+
+  <img src="_images/stm32l4x6-ls-macos.png" width="700px">
+
+- Open serial port in terminal using picocom
+
+  ```bash
+  picocom -b 115200 --imap lfcrlf /dev/tty<port>
   ```
 
   <details>
   <summary>How to get picocom (Ubuntu 20.04)</summary>
 
-  ```
+  ```bash
   sudo apt-get update && \
   sudo apt-get install picocom
   ```
 
+  </details>
+  <details>
+  <summary>How to get picocom (macOS)</summary>
+
+  ```bash
+  brew update &&\
+  brew 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
 
-To flash the image to the board you will need `openocd` in version 0.11. When installing openocd using `apt-get` version can be out of date (0.10). You can check it using
+To flash the image to the board you will need `openocd` in version 0.11 or 0.12. You can check it using
 
 ```bash
 openocd -v
@@ -59,30 +93,64 @@ openocd -v
   <details>
   <summary>How to get openocd in version 0.11 (Ubuntu 20.04)</summary>
 
-  - download `openocd-0.11.0-rc2` from [here](https://launchpad.net/ubuntu/+source/openocd)
-  - enter the downloaded directory
+To install from the default repositoriy:
+
+- use `apt-get`
 
+  ```bash
+  sudo apt-get install openocd
   ```
-  cd openocd-0.11.0-rc2
+
+- check if the version is correct
+
+  ```bash
+  openocd -v
   ```
 
-  - install openocd
+To install manually:
+
+- download `openocd-0.11.0-rc2` from [here](https://launchpad.net/ubuntu/+source/openocd)
+- enter the downloaded directory
 
+  ```bash
+  cd openocd-0.11.0-rc2
   ```
+
+- install openocd
+
+  ```bash
   sudo apt-get install libusb-1.0 && ./configure --enable-stlink && make && sudo make install
   ```
 
-  - check if the version is correct
+- check if the version is correct
 
-  ```
+  ```bash
   openocd -v
   ```
 
   </br>
   <img src="_images/openocd-version.png" width="700px">
   </br>
 
-  </details> 
+  </details>
+
+  <details>
+  <summary>How to get openocd (macOS) </summary>
+
+  - install openocd
+
+  ```bash
+  brew update &&\
+  brew install open-ocd
+  ```
+
+  - check if the version is correct
+
+  ```bash
+  openocd -v
+  ```
+
+  </details>
 
 If you have openocd, next you can use the following script:
 
@@ -108,11 +176,12 @@ Phoenix-RTOS will be launched and the `psh` shell command prompt will appear in
 
 <img src="_images/stm32l4x6-start.png" width="700px">
 
- - Note: You can also enter plo (Phoenix-RTOS loader) by pressing any button, for example, `enter` within some time after reset (using `RESET B2`).
+- Note: You can also enter plo (Phoenix-RTOS loader) by pressing any button, for example, `enter` within some
+ time after reset (using `RESET B2`).
 
 To get the available command list please type:
 
-```
+```bash
 help
 ```