Enhance build scripts, logging, and documentation for Zephyr and Linux targets; refactor state machine handling and improve error reporting in core functions. (#81)

Signed-off-by: Krisztian Szilvasi <34309983+kr-t@users.noreply.github.com>

Author: kr-t

.github/workflows/build.yml

@@ -33,60 +33,71 @@ jobs:
 
       - name: Build native_sim
         run: |
-          west build --pristine -b native_sim ./application -d build -- -DMODULE_EXT_ROOT=$(pwd)/application
+          west build --pristine -b native_sim ./application -d build -- -DMODULE_EXT_ROOT=$(pwd)/application | tee zephyr_build_native_sim.log
       
-      - name: Upload build native_sim artifact
+      - name: Upload native_sim build artifact
         if: job.status == 'success'
         uses: actions/upload-artifact@v4
         with:
-          name: zephyr-build-native-sim
-          path: build/
+          name: ocre-zephyr-native_sim-app #TODO: modify when matrix will added
+          path: build/zephyr/zephyr.exe
+
+      - name: Upload native_sim build log
+        uses: actions/upload-artifact@v4
+        with:
+          name: zephyr_build_native_sim_log
+          path: zephyr_build_native_sim.log
 
       - name: Build b_u585i_iot02a
-        if: runner.environment == 'self-hosted'
         run: |
-          west build --pristine -b b_u585i_iot02a ./application -d build -- -DMODULE_EXT_ROOT=$(pwd)/application
-            
-      - name: Upload firmware artifact
-        if: runner.environment == 'self-hosted' && job.status == 'success'
+          west build --pristine -b b_u585i_iot02a ./application -d build -- -DMODULE_EXT_ROOT=$(pwd)/application | tee zephyr_build_b_u585.log
+      
+      - name: Upload b_u585 build artifact
+        if: job.status == 'success'
         uses: actions/upload-artifact@v4
         with:
-          name: firmware
+          name: ocre-zephyr-b_u585-app #TODO: modify when matrix will added
           path: build/zephyr/zephyr.bin
 
+      - name: Upload b_u585 build log
+        uses: actions/upload-artifact@v4
+        with:
+          name: zephyr_build_b_u585_log
+          path: zephyr_build_b_u585.log
+
   run-zephyr-native-sim:
     runs-on: zephyr-xlarge-runner
     needs: build-zephyr
     container:
       image: ghcr.io/zephyrproject-rtos/ci:v0.26-branch
       options: --user root
     steps:
-      - name: Download Zephyr build artifacts
+      - name: Download Zephyr build artifact (native_sim)
         uses: actions/download-artifact@v4
         with:
-          name: zephyr-build-native-sim
+          name: ocre-zephyr-native_sim-app
           path: build/
 
       - name: Run Zephyr binary and check output
-        working-directory: build/zephyr/
+        working-directory: build
         run: |
           EXPECTED_LOG="Hello World from Ocre!"
           echo "Running Zephyr (native_sim)..."
           chmod +x zephyr.exe
-          stdbuf -oL -eL timeout 20s ./zephyr.exe | tee zephyr_app.log
+          stdbuf -oL -eL timeout 20s ./zephyr.exe | tee zephyr_run_native_sim.log
           echo "===== Checking for expected log ====="
-          if grep -q "$EXPECTED_LOG" zephyr_app.log; then
+          if grep -q "$EXPECTED_LOG" zephyr_run_native_sim.log; then
             echo "[OK] Found expected log: $EXPECTED_LOG"
           else
             echo "[ERROR] Expected log not found: $EXPECTED_LOG"
             exit 1
           fi
 
-      - name: Upload app logs
+      - name: Upload run app logs
         uses: actions/upload-artifact@v4
         with:
-          name: zephyr-app-log
-          path: build/zephyr/zephyr_app.log
+          name: zephyr_run_native_sim_log
+          path: build/zephyr_run_native_sim.log
 
   build-linux:
     runs-on: ubuntu-latest
@@ -101,36 +112,45 @@ jobs:
           cd application
           git submodule update --init --recursive
 
-      - name: Build Linux
+      - name: Build Linux x86_64
         run: |
           cd application
-          ./build.sh -t l
+          ./build.sh -t l | tee linux_build.log
     
-      - name: Upload build artifacts
+      - name: Upload Linux build log
         uses: actions/upload-artifact@v4
         with:
-          name: linux-build
-          path: application/build/
+          name: linux_build_log
+          path: application/linux_build.log
+
+      - name: Upload x86_64 build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ocre-ubuntu-x86_64-app
+          path: |
+            application/build/app
+            application/build/src
 
   run-linux:
     runs-on: ubuntu-latest
     needs: build-linux
     steps:
-      - name: Download Linux build artifacts
+      - name: Download Linux build artifact
         uses: actions/download-artifact@v4
         with:
-          name: linux-build
+          name: ocre-ubuntu-x86_64-app
           path: application/build/
 
       - name: Run Linux binary and check output
         working-directory: application/build
         run: |
+          ls -l
           EXPECTED_LOG="Hello World from Ocre!"
           chmod +x app
           echo "Running application..."
-          stdbuf -oL -eL timeout 20s ./app | tee linux_app.log
+          stdbuf -oL -eL timeout 20s ./app | tee linux_run.log
           echo "===== Checking for expected log ====="
-          if grep -q "$EXPECTED_LOG" linux_app.log; then
+          if grep -q "$EXPECTED_LOG" linux_run.log; then
             echo "[OK] Found expected log: $EXPECTED_LOG"
           else
             echo "[ERROR] Expected log not found: $EXPECTED_LOG"
@@ -140,18 +160,18 @@ jobs:
       - name: Upload app logs
         uses: actions/upload-artifact@v4
         with:
-          name: linux-app-log
-          path: application/build/linux_app.log
+          name: linux_run_log
+          path: application/build/linux_run.log
 
   flash:
     needs: build-zephyr
     runs-on: zephyr-xlarge-runner
     steps:
-      - name: Download firmware
+      - name: Download Zephyr build artifact(b_u585i_iot02a)
         if: runner.environment == 'self-hosted'
         uses: actions/download-artifact@v4
         with:
-          name: firmware
+          name: ocre-zephyr-b_u585-app
 
       - name: Flash b_u585i_iot02a
         if: runner.environment == 'self-hosted'

README.md

@@ -103,8 +103,6 @@ cd ocre-runtime
 git submodule update --init --recursive
 ```
 
----
-
 ## Building and Running
 
 ### Using the `build.sh` Script (Recommended)
@@ -114,13 +112,16 @@ Ocre provides a convenient `build.sh` script to simplify building and running fo
 #### Usage
 
 ```sh
-./build.sh -t <target> [-r] [-f <file1> [file2 ...]] [-b] [-h]
+./build.sh -t <target> [-r] [-f <file1> [file2 ...]] [-b] <board> [-h]
 ```
 
 - `-t <target>`: **Required**. `z` for Zephyr, `l` for Linux.
 - `-r`: Run after build (optional).
 - `-f <file(s)>`: Specify one or more input files (optional).
-- `-b`: (Zephyr only) Build for `b_u585i_iot02a` board instead of `native_sim`.
+- `-b <board>`: (Zephyr only) Select a zephyr board instead of the default `native_sim`:
+    - `uw`          -> b_u585i_iot02a + W5500
+    - `ue`          -> b_u585i_iot02a + ENC28J60
+    - `your_option` -> any Zephyr-supported board
 - `-h`: Show help.
 
 #### Examples
@@ -179,7 +180,34 @@ make
 - The script checks build success and only runs the application if the build completes successfully.
 - The `mini-samples` directory contains a "Hello World" container, which is hardcoded as a C array. When Ocre is run without input file arguments, it executes this sample container by default. If an input file is provided, Zephyr will convert that file into a C array at build time and run it as a container. On Linux, this conversion does not occur — instead, Ocre simply opens and reads the provided file(s) directly from the filesystem.
 
----
+## Sample Output
+
+#### Zephyr (b_u585i_iot02a)
+```sh
+./build.sh -t z -r -b ue
+```
+
+##### Output
+```sh
+Target is: Zephyr
+Building for b_u585i_iot02a with ENC28J60 support
+Linking C executable zephyr/zephyr.elf
+Ocre runtime started
+Hello World from Ocre!
+```
+
+#### Linux
+```sh
+./build.sh -t l -r
+```
+
+##### Output
+```sh
+Target is: Linux
+[100%] Built target app
+Ocre runtime started
+Hello World from Ocre!
+```
 
 ## License
 

boards/native_sim.conf

@@ -1,6 +1,5 @@
-CONFIG_UART_NATIVE_POSIX_PORT_1_ENABLE=y
-CONFIG_NATIVE_UART_0_ON_STDINOUT=y
-CONFIG_UART_NATIVE_POSIX=y
+CONFIG_UART_NATIVE_PTY_0_ON_STDINOUT=y
+CONFIG_UART_NATIVE_PTY=y
 CONFIG_FLASH_SIMULATOR=y
 CONFIG_ENTROPY_GENERATOR=y
 CONFIG_TEST_RANDOM_GENERATOR=y

build.sh

@@ -6,14 +6,17 @@ show_help() {
     echo "  -t <target>   (Required) Specify the target. z for Zephyr and l for Linux"
     echo "  -r            (Optional) Specify whether run after the build"
     echo "  -f <file(s)>  (Optional) Specify one or more input files"
-    echo "  -b            (Optional) Only Zephyr: build for b_u585i_iot02a instead of native_sim"
-    echo "  -h             Display help"
+    echo "  -b <board>    (Optional, Zephyr only) Select board:"
+    echo "                  uw  -> b_u585i_iot02a + W5500"
+    echo "                  ue  -> b_u585i_iot02a + ENC28J60"
+    echo "  note: when no board is selected, native_sim is the default target for Zephyr"
+    echo "  -h            Display help"
     exit 0
 }
 
 RUN_MODE=false  # Default: Run mode disabled
 INPUT_FILES=()
-ZEPHYR_BOARD="native_sim"
+BOARD_ARG="native_sim"
 
 # resolve absolute paths (portable, no readlink -f)
 abs_path() {
@@ -29,6 +32,10 @@ abs_path() {
 while [[ $# -gt 0 ]]; do
     case "$1" in
         -t)
+            if [[ -z "$2" || "$2" =~ ^- ]]; then
+                echo "Error: -t requires a value (z or l)" >&2
+                exit 1
+            fi
             TARGET="$2"
             shift 2
             ;;
@@ -44,8 +51,12 @@ while [[ $# -gt 0 ]]; do
             done
             ;;
         -b)
-            ZEPHYR_BOARD=b_u585i_iot02a
-            shift
+            if [[ -z "$2" || "$2" =~ ^- ]]; then
+                echo "Error: -b requires a board argument" >&2
+                exit 1
+            fi
+            BOARD_ARG="$2"
+            shift 2
             ;;
         -h)
             show_help
@@ -66,21 +77,39 @@ fi
 
 # Check if required argument is provided
 if [[ "$TARGET" == "z" ]]; then
-    echo "Target is: Zephyr's $ZEPHYR_BOARD"
+    echo "Target is: Zephyr"
     cd ..
+    case "$BOARD_ARG" in
+        uw)
+            ZEPHYR_BOARD="b_u585i_iot02a"
+            CONF_EXTRA=""
+            echo "Building for b_u585i_iot02a with W5500 support"
+            ;;
+        ue)
+            ZEPHYR_BOARD="b_u585i_iot02a"
+            CONF_EXTRA="-DCONF_FILE=prj.conf\;boards/${ZEPHYR_BOARD}.conf\;boards/enc28j60.conf \
+                        -DDTC_OVERLAY_FILE=boards/${ZEPHYR_BOARD}.overlay\;boards/enc28j60.overlay"
+            echo "Building for b_u585i_iot02a with ENC28J60 support"
+            ;;
+        *)
+            ZEPHYR_BOARD="$BOARD_ARG"
+            CONF_EXTRA=""
+            echo "Building for board: $ZEPHYR_BOARD"
+            ;;
+    esac
+
     if [[ ${#INPUT_FILES[@]} -gt 0 ]]; then
         echo "Input files provided: ${INPUT_FILES[*]}"
-        rm flash.bin 
+        rm flash.bin
         west build -p -b $ZEPHYR_BOARD ./application -d build -- \
-        -DMODULE_EXT_ROOT=`pwd`/application -DOCRE_INPUT_FILE="${INPUT_FILES[0]}" -DTARGET_PLATFORM_NAME=Zephyr || exit 1
-        # Note: Only the first file is passed to OCRE_INPUT_FILE, adapt as needed for multiple files
+            -DMODULE_EXT_ROOT=`pwd`/application -DOCRE_INPUT_FILE="${INPUT_FILES[0]}" -DTARGET_PLATFORM_NAME=Zephyr $CONF_EXTRA || exit 1
     else
         rm flash.bin
-        west build -p -b $ZEPHYR_BOARD  ./application -d build -- \
-        -DMODULE_EXT_ROOT=`pwd`/application -DTARGET_PLATFORM_NAME=Zephyr || exit 1
+        west build -p -b $ZEPHYR_BOARD ./application -d build -- \
+            -DMODULE_EXT_ROOT=`pwd`/application -DTARGET_PLATFORM_NAME=Zephyr $CONF_EXTRA || exit 1
     fi
 elif [[ "$TARGET" == "l" ]]; then
-    echo "Target is: Linux x86_64"
+    echo "Target is: Linux"
     if [[ ! -d "build" ]]; then
         echo "build folder does not exist. Creating: build"
         mkdir -p "build"

src/ocre/api/ocre_api.c

@@ -5,7 +5,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#ifndef _GNU_SOURCE
 #define _GNU_SOURCE
+#endif
 
 #include <stdio.h>
 #include <sys/utsname.h>

src/ocre/api/ocre_api.h

@@ -10,7 +10,7 @@
 #ifndef OCRE_API_H
 #define OCRE_API_H
 
-#define OCRE_API_POSIX_BUF_SIZE 75
+#define OCRE_API_POSIX_BUF_SIZE 80
 
 #ifndef OCRE_SYSTEM_NAME
 #define OCRE_SYSTEM_NAME "Project Ocre"
@@ -29,4 +29,4 @@ int _ocre_posix_uname(wasm_exec_env_t exec_env, struct _ocre_posix_utsname *name
 
 extern NativeSymbol ocre_api_table[];
 extern int ocre_api_table_size;
-#endif
+#endif