> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the remoteprocessor (remoteproc) subsystems

The remoteproc framework is used to load firmware into other subsystems, such as the audio digital signal processor (aDSP) and compute digital signal processor (cDSP) on Qualcomm<sup>®</sup> platforms.

The remoteproc framework is divided into two parts:

* Core framework—The core framework contains a common logic. It loads the firmware and starts or stops the remote processor.
* Remoteproc drivers—The drivers contain platform-specific operations to manage the corresponding cores. A remoteproc driver registers a remoteproc instance and a set of operations with the core framework.

Several heterogeneous remote processors are present on an SoC in an asymmetric multiprocessing (ASMP) configuration. The remote processors run different instances of firmware or OS.

For more information about the standard framework that the Qualcomm Linux uses to manage other cores, see [Remote Processor Framework](https://docs.kernel.org/staging/remoteproc.html).

## Qualcomm remoteproc support

Qualcomm has enhanced the remoteproc framework for peripheral firmware authentication using the upstream PAS driver.

The Remoteproc driver in Qualcomm Linux implements a peripheral authentication service (PAS) driver, which is a TrustZone-based peripheral image loader for remote processors on Qualcomm SoC devices.

For more information, see [qcom\_q6v5\_pas.c](https://github.com/torvalds/linux/blob/master/drivers/remoteproc/qcom_q6v5_pas.c).

The remote processors are used to manage the lifecycle of various co-processors, such as aDSP, cDSP, modem peripheral subsystem (MPSS), and wireless processor subsystem (WPSS). The supported co-processors on QCS6490-based boards and Dragonwing<sup>™</sup> RB3 Gen 2 Development Kit are aDSP, cDSP, and WPSS.

<Note>
  List of supported remote processor subsystems depends upon the SoC in use.
</Note>

**User interface:** The remoteproc framework tracks the registered remoteproc devices and provides a user interface to boot and shutdown the devices. The user space can query and change the current state of a remoteproc using the following `sysfs` interface:

```text theme={null}
remoteproc user space interface
# start remoteproc:
  echo "start" > /sys/class/remoteproc/remoteprocN/state

# stop remoteproc:
  echo "stop" > /sys/class/remoteproc/remoteprocN/state
```

<div className="flex flex-col items-center gap-2">
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Kernel/media/remoteproc-framework.svg?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=7106e420e6a7c3f7c8d274e12f8d79c1" alt="Figure : Remoteproc support" width="976" height="744" data-path="System/Kernel/media/remoteproc-framework.svg" />

  <p className="text-sm text-gray-700">
    Figure : Remoteproc support
  </p>
</div>

## Configure remoteproc recovery and subsystem restart

The remoteproc sub-devices manage communication contexts for remote processor subsystem crash and recovery scenarios.

Entities, such as communication contexts, must determine when a remote processor boots or shuts down. Each sub-device has two operations:

* `probe()` called after the remoteproc `start()`
* `remove()` called before `stop()`

When a fatal error occurs on a remote processor, the remoteproc driver handles it and invokes `rproc_report_crash()`, which triggers recovery of the faulty remote processor.

The recovery handler does the following:

<div className="flex flex-col items-center gap-2">
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Kernel/media/Remoteproc-recovery.svg?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=77736732509d0645122919b4d2b7a966" alt="Figure: Remoteproc crash sequence" width="1071" height="204" data-path="System/Kernel/media/Remoteproc-recovery.svg" />

  <p className="text-sm text-gray-700">
    Figure: Remoteproc crash sequence
  </p>
</div>

Start remoteproc instanceReload firmwareInvoke coredump generatorStop remoteproc instance

**Figure: Remoteproc crash sequence**

To enable and disable recovery using the recovery `debugfs` node from the user space, do the following:

```text theme={null}
mount -t debugfs nodev /sys/kernel/debug
echo disabled > /sys/kernel/debug/remoteproc/remoteprocN/recovery
```

## Enable or disable core dump

Remote processor core dumps are supported for debugging the subsystem crash issues using the Qualcomm Linux kernel devcoredump feature.

When a subsystem crash occurs, devcoredump exposes a snapshot of the memory of the recovering remoteproc in the `/sys/class/devcoredump/devcdN/data` node, and an associated crash `uevent` is sent to the user space. When the sysfs node is read, the sysfs provides the segments in an ELF container, and a write operation frees up the resources and destroys the devcoredump instance.

A debugfs node is exposed to enable and disable core dump from the user space.

```text theme={null}
# Disable core dumps:
  echo disabled > /sys/kernel/debug/remoteproc/remoteprocN/coredump

# Enable core dumps:
  echo enabled > /sys/kernel/debug/remoteproc/remoteprocN/coredump
#
# N represents the index number of the remote processor.
```

<Note>
  To collect the full RAM dump for crash analysis, Qualcomm SoCs implement kernel panic on remoteproc crash (fatal error on remote processor). The kernel panic mode is enabled only when the core dump is disabled.
</Note>

The devcoredump `/sys/class/devcoredump/devcdN/data` node is created on a subsystem crash only if core dump is enabled for the subsystem. To enable the core dump, run the `echo enabled > /sys/kernel/debug/remoteproc/remoteprocN/coredump` command. The `devcdN/data` node is temporary and is removed after a timeout. To debug the issues, use the `copy` command to copy the `devcdN/data` node to your local device for secure usage. The delete timeout is defined in `base/devcoredump.c`.

The following is an example command to copy the core dumps:

```text theme={null}
# Copy Core dump to a local device
  cp /sys/class/devcoredump/devcdN/data > /var/spool/crash/dump_file.elf
#
# N represents the index of core dump. It is incremented each time a new core dump is generated.
```

To transfer the core dump file to a host device and debug the issues, use the Qualcomm Crash Analysis Portal (QCAP).

<Note>
  For more information about QCAP, see Parse RAM dumps using QCAP.
</Note>

## Configure the remoteproc node and firmware load in DT

The remoteproc devices are configured in the respective device tree files using the DT bindings. The configuration includes compatible device names, memory regions, interrupt settings, and clock references, according to the DT bindings, in the `Documentation/devicetree/bindings/remoteproc/` directory.

The following example shows the QCS6490 aDSP remoteproc device tree configuration in the `arch/arm64/boot/dts/qcom/qcs6490.dtsi` (renamed to `kodiak.dtsi` in kernel v6.19 and later):

```text theme={null}
remoteproc_adsp: remoteproc@3000000 {
          compatible = "qcom,sc7280-adsp-pas";
          reg = <0x0 0x03000000 0x0 0x100>;

          interrupts-extended = <&pdc 6 IRQ_TYPE_EDGE_RISING>,
                                  <&adsp_smp2p_in 0 IRQ_TYPE_EDGE_RISING>,
                                  <&adsp_smp2p_in 1 IRQ_TYPE_EDGE_RISING>,
                                  <&adsp_smp2p_in 2 IRQ_TYPE_EDGE_RISING>,
                                  <&adsp_smp2p_in 3 IRQ_TYPE_EDGE_RISING>,
                                  <&adsp_smp2p_in 7 IRQ_TYPE_EDGE_RISING>;
          interrupt-names = "wdog", "fatal", "ready", "handover",
                          "stop-ack", "shutdown-ack";

          clocks = <&rpmhcc RPMH_CXO_CLK>;
          clock-names = "xo";
          <snip>
 };
```

Check the IQ-9075 device tree configuration file in the `arch/arm64/boot/dts/qcom/lemans.dtsi` path.

<Note>
  To get the device tree configuration file for all the Qualcomm SoCs, see the respective platform DTSI file.
</Note>

All firmware files are present in the `/lib/firmware` directory in `rootfs` and the related configurations are done in the corresponding board device tree `arch/arm64/boot/dts/qcom/qcs6490-rb3gen2.dts` file. For other Qualcomm hardware SoCs, see `arch/arm64/boot/dts/qcom/<SoC>-<board>.dts` files.

The following example shows the remoteproc DT configuration:

```text theme={null}
&remoteproc_adsp {
firmware-name = "qcom/qcs6490/adsp.mdt";
status = "okay";
};
```

### **Remoteproc reference logs**

The following log is displayed when a remoteproc boots successfully:

```text theme={null}
**
\# remoteproc success**
"remoteproc remoteproc1: remote processor 4080000.remoteproc is now up"
```

The following log is displayed when a remoteproc firmware load fails:

```text theme={null}
**
\# remoteproc failure**
Error log: "remoteproc remoteproc0: Direct firmware load for qcom/qcs6490/modem.mdt failed with error -2"

# Caused by: error loading firmware.
# Solution: ensure that the modem firmware is copied to /lib/firmware/qcom/qcs6490 in rootfs.
```