ACPI SSDT workflow automation and D4XX firmware documentation refresh

doc/acpi/kernelspace.md

@@ -328,18 +328,14 @@ Install acpica tools version [20260408](https://github.com/acpica/acpica/release
     make
     sudo make install
 
-### Compile ASL source file
+### Compile ASL source file and load SSDT initramfs
 
-Run helper script to generate initramfs image from ASL source file and copy to /boot
+Run helper script to automate ASL compilation, initramfs image generation, and GRUB configuration (you will be prompted for sudo).
 
-    ../../script/gen_ssdt.sh ../../acpi/{create-your-own.asl}
+    ../../script/acpi/gen_ssdt.sh ../../acpi/{create-your-own.asl}
 
-### Load SSDT initramfs
+Reboot into BIOS settings and make sure all camera-related BIOS settings are disabled
 
-Add the following line to /etc/default/grub for GRUB to load the SSDT initramfs. Update and reboot. Make sure all camera-related BIOS settings are disabled.
-
-    echo 'GRUB_EARLY_INITRD_LINUX_CUSTOM="img_ssdt.img"' | sudo tee -a /etc/default/grub
-    sudo update-grub
     sudo reboot
 
 #### Unload SSDT initramfs

doc/d4xx/firmware-update.md

@@ -0,0 +1,89 @@
+## Description
+
+This document provides the steps to update the firmware (FW) of the D400 series camera using realsense-viewer or rs-fw-update.
+
+> **Note:** The steps below were verified with FW v5.17.3.10. The same procedure applies to other FW versions. Replace the version number and binary file name with the FW version you intend to install.
+
+## Table of Contents
+
+- [Download Firmware](#download-firmware)
+- [Prerequisites](#prerequisites)
+- [Firmware Upgrade Procedure](#firmware-upgrade-procedure)
+- [Option 1: Upgrade by realsense-viewer](#option-1-upgrade-by-realsense-viewer)
+- [Option 2: Upgrade by rs-fw-update](#option-2-upgrade-by-rs-fw-update)
+
+## Download Firmware
+
+Download the desired FW version from [Firmware releases D400 - RealSense](https://dev.realsenseai.com/docs/firmware-releases-d400/).
+
+The FW binary file follows the naming convention `Signed_Image_UVC_<version>.bin` (for example, `Signed_Image_UVC_5_17_3_10.bin` for FW v5.17.3.10).
+
+## Prerequisites
+Before updating firmware, make sure the following steps are completed:
+
+1. [Pipeline Configuration](./userspace-gmsl.md#advanced-pipeline-configuration---per-stream-configuration)
+2. [Symlink Creation](./userspace-gmsl.md#create-symlinks-using-upstream-rs-enumsh)
+3. [librealsense SDK compilation](./userspace-gmsl.md#compile-librealsense-sdk-from-source)
+
+
+## Firmware Upgrade Procedure
+
+Two options are available to upgrade the firmware.
+
+### Option 1: Upgrade by realsense-viewer
+
+1. Click **More -> Update Firmware** in realsense-viewer.
+2. Select the FW binary file of the desired FW version.
+3. Restart realsense-viewer after the upgrade completes.
+
+![realsense-viewer firmware update](./image/realsense-viewer-fw-update.png)
+
+### Option 2: Upgrade by rs-fw-update
+
+1. List connected devices to get the camera serial number:
+
+    ```bash
+    rs-fw-update -l
+    ```
+
+    Example output:
+
+    ```bash
+    Connected devices:
+    1) [GMSL] RealSense D457 s/n 261122300942, update serial number: 224543110084, firmware version: 5.15.1.55
+    ```
+
+    Use the value next to `s/n` as the serial number for `-s`.
+2. Run the firmware update:
+
+    ```bash
+    rs-fw-update -f FW_BINARY_FILE -s SERIAL_NUMBER
+    ```
+
+    Example to update to FW v5.17.3.10:
+
+    ```bash
+    rs-fw-update -f Signed_Image_UVC_5_17_3_10.bin -s 261122300942
+    ```
+
+Sample output:
+
+```bash
+$ sudo ./rs-fw-update -f  Signed_Image_UVC_5_17_3_10.bin -s 261122300942
+ 09/07 18:55:34,714 WARNING [135123028492160] (context.cpp:41) No valid configuration file found at : /root/.realsense-config.json loading defaults
+
+Search for device with serial number: 261122300942
+
+Updating device FW:
+[GMSL] RealSense D401 s/n 261122300942, update serial number: 224543110084, firmware version: 5.15.1.55
+
+Firmware update started. Please don't disconnect device!
+
+Firmware update progress: 100[%]
+
+Firmware update done
+
+Waiting for device to reconnect...
+
+Device 261122300942 successfully updated to FW: 5.17.3.10
+```

doc/d4xx/userspace-gmsl.md

@@ -6,6 +6,9 @@ This document describes the configuration settings for the D457 GMSL sensor usin
 > [acpi/kernelspace.md](../acpi/kernelspace.md) \
 > [acpi/userspace-gmsl.md](../acpi/userspace-gmsl.md)
 
+> **If firmware update is required:** refer to [firmware-update.md](./firmware-update.md).
+> Firmware update is required to resolve the long-duration test case issue for the D457 and to support the external frame sync feature.
+
 ---
 ## ACPI Setup - ASL Configuration
 
@@ -635,7 +638,7 @@ For more details, please refer to icamerasrc device-name property for more detai
 ### Verify Stream Using RealSense SDK
 
 >Prerequisites:\
->1. Completed [Pipeline Configuration](./userspace-gmsl.md#configure-pipeline-using-mc-setupsh)\
+>1. Completed [Pipeline Configuration](./userspace-gmsl.md#advanced-pipeline-configuration---per-stream-configuration)\
 >2. Completed [Symlinks Creation](./userspace-gmsl.md#create-symlinks-using-upstream-rs-enumsh)\
 >3. Completed [librealsense SDK compilation](./userspace-gmsl.md#compile-librealsense-sdk-from-source)
 

script/gen_ssdt.sh → script/acpi/gen_ssdt.sh

@@ -15,10 +15,27 @@
 # limitations under the License.
 #
 
-set -ex
 shopt -s nullglob
 
+IASL_VERSION="$(iasl -v 2>&1 | grep -oE '[0-9]{8}' | head -n1)"
+if [ -z "$IASL_VERSION" ]; then
+    echo "ERROR: unable to determine iasl version" >&2
+    exit 1
+fi
+
+if [ "$IASL_VERSION" -lt 20260408 ]; then
+    echo "ERROR: iasl version $IASL_VERSION is too old; need 20260408 or newer" >&2
+    exit 1
+fi
+
+if ! grep -qF 'GRUB_EARLY_INITRD_LINUX_CUSTOM="img_ssdt.img"' /etc/default/grub; then
+    echo 'GRUB_EARLY_INITRD_LINUX_CUSTOM="img_ssdt.img"' | sudo tee -a /etc/default/grub
+    sudo update-grub
+fi
+
+FW_BASE_DIR="/tmp"
 DIR="kernel/firmware/acpi"
+SSDT_IMG="$FW_BASE_DIR/img_ssdt.img"
 
 if [ -z "$1" ]; then
     echo "Usage: $0 <asl file>"
@@ -31,9 +48,10 @@ AML="${1%.asl}.aml"
 
 # Remove any stale outputs from a previous run so a failed recompile
 # cannot leave the old AML in place to be packaged below.
-rm -f "$AML" ./img_ssdt.img
+rm -f "$AML" "$SSDT_IMG"
 
 iasl -li "$1"
+ASL_DIR="$PWD"
 
 # iasl can return 0 with warnings but skip writing the AML on errors;
 # guard against that as well.
@@ -42,9 +60,22 @@ if [ ! -f "$AML" ]; then
     exit 1
 fi
 
+cd "$FW_BASE_DIR"
 mkdir -p "$DIR"
 rm -f "$DIR"/*
-cp "$AML" "$DIR"
-find kernel | cpio -H newc --create > img_ssdt.img
+cp "$ASL_DIR"/"$AML" "$FW_BASE_DIR"/"$DIR"
+find kernel | cpio -H newc --create > "$SSDT_IMG"
+
+if [ -f "$SSDT_IMG" ]; then
+    echo "Successful generation of $SSDT_IMG"
+else
+    echo "ERROR: failed to generate $SSDT_IMG" >&2
+    exit 1
+fi
 
-sudo cp img_ssdt.img /boot
+if sudo cp "$SSDT_IMG" /boot; then
+    echo "Successful copy of $SSDT_IMG to /boot"
+else
+    echo "ERROR: failed to copy $SSDT_IMG to /boot" >&2
+    exit 1
+fi