Merge branch 'main' of https://git.beagleboard.org/docs/docs.beagleboard.io

boards/beaglev/fire/demos-and-tutorials/mchp-fpga-tools-installation-guide.rst

@@ -3,7 +3,7 @@
 Microchip FPGA Tools Installation Guide
 #########################################
 
-Instructions for installing the Microchip FPGA tools on a Ubuntu 20.04 desktop.
+Instructions for installing the Microchip FPGA tools on a Ubuntu 20.04 or Ubuntu 22.04 desktop.
 
 .. important::
 
@@ -14,36 +14,39 @@ Instructions for installing the Microchip FPGA tools on a Ubuntu 20.04 desktop.
 
    Make sure people know about the alternative and we provide links to details on that before we send them down this process.
 
-Install Libero 2023.2
-************************
+
+Install Libero 
+**************
+
+.. note:: Libero 2023.2, 2024.1 or 2024.2 should work. 2024.2 is used as an example.
+
+Create a folder named Microchip in your /home folder
 
 - Download installer from the `Microchip's fpga and soc design tools section <https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/fpga/libero-software-later-versions>`_.
 - Install Libero
 
 .. code-block::
 
-  unzip Libero_SoC_v2023.2_lin.zip
-
-  cd Libero_SoC_v2023.2_lin/
+  unzip Libero_SoC_v2024.2_lin.zip
 
   ./launch_installer.sh
 
 .. important:: 
     Do not use the default location suggested by the Libero installer. 
-    Instead of /usr/local/Microchip/Libero_SoC_v2023.2 install into ~/Microchip/Libero_SoC_v2023.2
+    Instead of /usr/local/Microchip/Libero_SoC_v2024.2 install into ~/Microchip/Libero_SoC_v2024.2
     
 Run the post installation script which will install missing packages:
 
 .. code-block::
 
-  sudo /home/<USER-NAME>/Microchip/Libero_SoC_v2023.2/Logs/req_to_install.sh
+  sudo /home/$USER/Microchip/Libero_SoC_v2024.2/Logs/req_to_install.sh
 
 No need to run the FlashPro hardware installation scripts. This will be taken care of as part of the SoftConsole installation.
 
 Install SoftConsole 2022.2
 ***************************
 
-- Download intaller from `Microchip website <https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/soc-fpga/softconsole>`_.
+- Download installer from `Microchip website <https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/soc-fpga/softconsole>`_.
 
 .. code-block::
 
@@ -63,7 +66,14 @@ Perform the post installation steps as described in the html file opened when yo
 Install the Libero licensing daemon
 ************************************
 
-Download the 64 bit Licensing Daemons from the `Microchip's daemons section <https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/fpga/licensing>`_
+Download the latest 64 bit Licensing Daemons from the `Microchip's fpga and soc design tools section <https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/fpga/libero-software-later-versions>`_
+
+* `Linux_Licensing_Daemon_11.19.6.0_64-bit.tar.gz <https://ww1.microchip.com/downloads/secure/aemdocuments/documents/fpga/media-content/FPGA/daemons/Linux_Licensing_Daemon_11.19.6.0_64-bit.tar.gz>`_
+* `Windows_Licensing_Daemon_11.19.6.0_64-bit.zip <https://ww1.microchip.com/downloads/secure/aemdocuments/documents/fpga/media-content/FPGA/daemons/Windows_Licensing_Daemon_11.19.6.0_64-bit.zip>`_
+
+
+Older Daemon downloads can be found at `Microchip's daemons section <https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/fpga/licensing>`_
+
 
 * `Linux_Licensing_Daemon_11.16.1_64-bit.tar.gz <https://ww1.microchip.com/downloads/aemdocuments/documents/fpga/media-content/FPGA/daemons/Linux_Licensing_Daemon_11.16.1_64-bit.tar.gz>`_
 * `Windows_Licensing_Daemon_11.16.1_64-bit.zip <https://ww1.microchip.com/downloads/aemdocuments/documents/fpga/media-content/FPGA/daemons/Windows_Licensing_Daemon_11.16.1_64-bit.zip>`_
@@ -75,7 +85,7 @@ Copy the downloaded file to the Microchip directory within your home directory a
 
   cd ~/Microchip
 
-  tar -xvf Linux_Licensing_Daemon_11.16.1_64-bit.tar.gz
+  tar -xvf Linux_Licensing_Daemon_11.19.6.0_64-bit.tar.gz
 
 
 Install the Linux Standard Base:
@@ -99,7 +109,19 @@ Request a Libero Silver license
     A MAC address looks something like 12:34:56::78:ab:cd when you use the "ip address" command to find out 
     its value on your Linux machine. However, you need to enter it as 123456abcd in this dialog box.
 
-You will get an email with a license.dat file. Copy it into the ~/Microchip/license directory. Edit the License.dat file to replace the <put.hostname.here> string with... localhost.
+You will get an email with a License.dat file. Copy it into the ~/Microchip/license directory. Replace `<put.hostname.here>` in `License.dat` with `localhost` and add Linux_Licensing_Daemon as the path to the daemons.
+
+The top of your license file should look something like this after editing. Your daemon files should be located in the  Linux_Licensing_Daemon folder inside the Microchip folder.
+
+.. code-block:: text
+
+   SERVER localhost 001584731680 1702
+   DAEMON actlmgrd  Linux_Licensing_Daemon/actlmgrd
+   # Starting Libero SOC v2024.2, customers are recommended ...
+   # DAEMON mgcld Linux_Licensing_Daemon/mgcld
+   DAEMON saltd Linux_Licensing_Daemon/saltd
+   VENDOR snpslmd  Linux_Licensing_Daemon/snpslmd
+
 
 Execute tool setup script
 ***************************
@@ -112,15 +134,38 @@ Download the script:
 
 :download:`setup-microchip-tools.sh <./setup-microchip-tools.sh>`
 
+Details:
+
+You can create a folder named FPGA-Tools-Setup and store the file there, although this is not required, as long as it is inside the Microchip folder.
+
+You shouldn't need to edit the script, as long as you have installed Libero inside a folder that follows the Libero_SoC_vXXXX.X format, or if you have multiple Libero versions installed and want to select a preferred one to use.
+
 Source the script:
 
 .. code-block::
 
+  sudo chmod +x setup-microchip-tools.sh
+
   . ./setup-microchip-tools.sh
 
 .. important:: 
   
-  Do not forget the leading dot. It matters. You will need to run this every time you restart your machine.
+  Do not forget the leading dot. It matters. You will need to run this every time you restart your machine. 
+
+Optionally, add this to the end of your `~/.bashrc` file to avoid running it each time on startup.
+
+First, open `~/.bashrc`:
+
+.. code-block:: bash
+
+   nano ~/.bashrc
+
+Then, add the following lines at the end:
+
+.. code-block:: bash
+
+   cd /home/$USER/Microchip/
+   . ./setup-microchip-tools.sh
 
 You can then start Libero to open an existing Libero project.
 

boards/beaglev/fire/demos-and-tutorials/setup-microchip-tools.sh

 #!/bin/bash
 
+# Gets Libero version
+
+dir=$(pwd)
+while [[ "$dir" != "/" ]]; do
+  for subdir in "$dir"/*/; do
+    if [[ $subdir =~ Libero_SoC_v([0-9]+\.[0-9]+)/ ]]; then
+      Libero_ver="${BASH_REMATCH[1]}"
+      break 2
+    fi
+  done
+  dir=$(dirname "$dir")
+done
+
+
+#Set preferred Libero version here if needed
+#Libero_ver=2023.2
+
+echo "Using Libero version:" $Libero_ver
+
+# Check if Libero_ver was set; if not, print an error and exit
+if [[ -z "$Libero_ver" ]]; then
+  echo "Error: No directory found matching the pattern 'Libero_SoC_vXXXX.Y/'"
+  return 1
+fi
+
 #===============================================================================
 # Edit the following section with the location where the following tools are
-# installed:
+# installed if they aren't in the default location:
 #   - SoftConsole (SC_INSTALL_DIR)
 #   - Libero (LIBERO_INSTALL_DIR)
 #   - Licensing daemon for Libero (LICENSE_DAEMON_DIR)
 #===============================================================================
+
 export SC_INSTALL_DIR=/home/$USER/Microchip/SoftConsole-v2022.2-RISC-V-747
-export LIBERO_INSTALL_DIR=/home/$USER/Microchip/Libero_SoC_v2023.2
+export LIBERO_INSTALL_DIR=/home/$USER/Microchip/Libero_SoC_v$Libero_ver
 export LICENSE_DAEMON_DIR=/home/$USER/Microchip/Linux_Licensing_Daemon
 export LICENSE_FILE_DIR=/home/$USER/Microchip/license
+export SMARTHLS_INSTALL_DIR=$LIBERO_INSTALL_DIR/SmartHLS-$Libero_ver/SmartHLS
 
 #===============================================================================
 # The following was tested on Ubuntu 20.04 with:
-#   - Libero 2023.2
+#   - Libero 2023.2 and 2024.1
+#   - SoftConsole 2022.2
+# It was also tested on Ubuntu 22.04 with:
+#   - Libero 2024.2
 #   - SoftConsole 2022.2
 #===============================================================================
 
@@ -28,8 +58,11 @@ export FPGENPROG=$LIBERO_INSTALL_DIR/Libero/bin64/fpgenprog
 # Libero
 #
 export PATH=$PATH:$LIBERO_INSTALL_DIR/Libero/bin:$LIBERO_INSTALL_DIR/Libero/bin64
-export PATH=$PATH:$LIBERO_INSTALL_DIR/Synplify/bin
-export PATH=$PATH:$LIBERO_INSTALL_DIR/Model/modeltech/linuxacoem
+export PATH=$PATH:$LIBERO_INSTALL_DIR/SynplifyPro/bin
+export PATH=$PATH:$LIBERO_INSTALL_DIR/ModelSimPro/modeltech/linuxacoem
+export PATH=$PATH:$SMARTHLS_INSTALL_DIR/bin
+export PATH=$PATH:$SMARTHLS_INSTALL_DIR/swtools/binutils/riscv-gnu-toolchain/bin
+
 export LOCALE=C
 export LD_LIBRARY_PATH=/usr/lib/i386-linux-gnu:$LD_LIBRARY_PATH
 

boards/beagley/ai/01-introduction.rst

@@ -13,7 +13,7 @@ Detailed overview
 ******************
 
 BeagleY-AI is based on the Texas Instruments AM67A Arm-based vision processor.  It features a quad-core 64-bit Arm®Cortex®-A53 CPU subsystem at 1.4GHz, 
-Dual general-purpose C7x DSP with Matrix Multiply Accelerator (MMA) capable of 4 TOPs each, Arm Cortex-R5 subsystem for low-latency 
+Dual general-purpose C7x DSP with Matrix Multiply Accelerator (MMA) capable of 4 TOPS (trillion-operations per second) combined (2 TOPS each), two available 800MHz Arm Cortex-R5 subsystems for low-latency 
 I/O and control, a 50 GFlop GPU, video and vision accelerators, and other specialized processing capability.
 
 .. table:: BeagleY-AI features

intro/beagle101/zephyr.rst

@@ -3,4 +3,174 @@
 Introduction to Zephyr RTOS
 ###########################
 
-.. todo:: Place-holder for Zephyr tutorial
+The Zephyr OS is built on a lightweight kernel optimized for resource-constrained 
+and embedded systems, making it an excellent fit for BeagleBoard projects. From simple 
+environmental sensors and LED-based designs to advanced embedded controllers, smart 
+devices, and IoT wireless applications. Zephyr is a scalable RTOS that can be used in
+multiple architectures and platforms.
+
+This article will focus on giving a starting point to learning Zephyr using a Beagleboard.
+
+Why Zephyr?
+***********
+
+- **Scalable**: Zephyr is designed to be scalable, from simple embedded systems to complex IoT applications.
+- **Modular**: Zephyr is designed to be modular, allowing you to use only the components you need.
+- **Open Source**: Zephyr is open-source, allowing you to modify and contribute to the project.
+- **Cross-platform**: Zephyr supports multiple architectures and platforms.
+- **Community**: Zephyr has a large community of developers and contributors.
+
+Getting Started with Zephyr
+****************************
+
+To get started with Zephyr, you will need to follow `Getting Started Guide by Zephyr 
+<https://docs.zephyrproject.org/latest/getting_started/index.html>`_. 
+By following the guide, you will be able to set up your development environment and get to 
+try out a zephyr sample applications.
+
+Delving into Zephyr
+*******************
+
+Once you have set up your development environment and tried out the sample applications,
+Let's delve into Zephyr by creating a simple application. We will now delve into breaking 
+the `blinky sample application <https://docs.zephyrproject.org/latest/samples/basic/blinky/README.html#blinky>`_ 
+and understand how it works.
+
+Here are the files in a simple Zephyr application:
+
+Let's pull blinky sample application from Zephyr repository to zephyrproject directory.
+
+.. code-block:: shell-session
+
+    cp -r zephyrproject/zephyr/samples/basic/blinky zephyrproject/app
+
+.. code-block:: none
+
+   app
+    ├── app.overlay
+    ├── CMakeLists.txt
+    ├── prj.conf
+    ├─ src
+    |   └── main.c
+    └── app.overlay
+
+
+- **CMakeLists.txt**: This file is used by CMake to build the application.
+- **app.overlay**: This file is used to configure the application changes based on the base device-tree.
+- **prj.conf**: This file is used to configure the Kconfig fragment that specifies application-specific values.
+- **VERSION**: This file is used to specify the version of the application.
+- **src/main.c**: This file contains the main application code.
+
+Let's take a look at the contents of the `main.c` file:
+
+.. code-block:: c
+
+    #include <stdio.h>
+    #include <zephyr/kernel.h>
+    #include <zephyr/drivers/gpio.h>
+
+These include statements include the necessary header files for the application such 
+as `stdio.h` for printf functions , `kernel.h` for kernel APIs like ms_sleep(), and 
+`gpio.h` for GPIO APIs for GPIO related functions.
+
+.. code-block:: c
+
+    #define LED_NODE DT_ALIAS(led0)
+
+As Zephyr uses a device tree to configure the hardware, this macro is used to get the 
+device tree node for the LED by resolving the alias `led0` alias present in the device tree,
+enabling the application to use the LED.
+
+.. code-block:: c
+
+    static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);
+
+``GPIO_DT_SPEC_GET`` fetches the GPIO configuration for led0.
+
+.. note::
+
+    build error on this line means your board is unsupported.
+
+.. code-block:: c
+
+    if (!gpio_is_ready_dt(&led)) {
+    return 0;
+    }
+
+This code checks if the GPIO is ready to use, if not it returns 0.
+
+.. code-block:: c
+
+    ret = gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
+
+This code configures the GPIO pin as an output pin and sets the initial state to active.
+
+.. note::
+
+    There are many other options other than GPIO_OUTPUT_ACTIVE, like GPIO_OUTPUT_INACTIVE, GPIO_INPUT, etc.
+    For more visit `Zephyr GPIO API <https://docs.zephyrproject.org/apidoc/latest/group__gpio__interface.html>`_,
+    GPIO input/output configuration flag section.
+
+.. code-block:: c
+
+    ret = gpio_pin_toggle_dt(&led);
+
+The ``gpio_pin_toggle_dt`` API helps in toggling the LED’s state
+
+.. code-block:: c
+
+    k_msleep(1000);
+
+This code makes the application sleep for 1000 milliseconds. part of the kernel API.
+
+As you have seen in this sample, there was not a single bit of hardware-specific code. 
+This is the beauty of Zephyr, which abstracts the hardware and provides a unified API
+
+Building the Application
+========================
+
+To build the application, you need to run the following commands:
+
+.. code-block:: none
+
+    west build -b <board-name>. 
+
+.. note::
+
+    West is a tool that helps in managing multiple repositories and build systems.
+    For more information, visit `West documentation <https://docs.zephyrproject.org/latest/guides/west/index.html>`_.
+
+After building the application, you will get the `zephyr.hex` file in the `build/zephyr` directory.
+
+Flashing the Application
+========================
+
+To flash the application, you need to run the following command:
+
+.. code-block:: none
+
+    west flash
+
+.. note::
+
+    1. To use west flash in BeagleConnect Freedom or BeaglePlay, it requires ``cc1352-flasher`` tool to be installed.
+        .. code-block:: none
+            pip3 install cc1352-flasher
+    2. At the moment, BeagleBone AI-64 doesn't support west flash. Please use the 
+        `documentation <https://docs.zephyrproject.org/latest/boards/beagle/beaglebone_ai64/doc/index.html>`_ 
+        provided by Zephyr for flashing the application.
+    3. At the moment, BeagleV-Fire doesn't support west flash. Please use the 
+        `documentation <https://docs.zephyrproject.org/latest/boards/beagle/beaglev_fire/doc/index.html>`_ 
+        provided by Zephyr for flashing the application.
+
+Result
+======
+
+After flashing the application, you will see the LED blinking every second.
+
+Recommended Reading
+*******************
+
+- `Zephyr Documentation <https://docs.zephyrproject.org/latest/index.html>`_
+- `Zephyr RTOS tutorial <https://github.com/maksimdrachov/zephyr-rtos-tutorial>`_
+- `awesome zephyr RTOS <https://github.com/zephyrproject-rtos/awesome-zephyr-rtos>`_