# Procedura di ripristino OpenCL + Vulkan — Orange Pi 5 Plus / Debian 12

## Obiettivo

Ripristinare l'accelerazione GPU sulla Orange Pi 5 Plus con:

- Debian 12 Bookworm
- kernel Rockchip 6.1.x già presente
- kernel Mali DDK g21p0-01eac0
- firmware Mali g21p0
- userspace Mali g24p0-00eac0
- Vulkan 1.3
- OpenCL 3.0

La procedura non deve modificare kernel, DTB o U-Boot.

# Attenzione

Non eseguire apt upgrade, apt full-upgrade, aggiornamenti del kernel o modifiche al bootloader come parte di questa procedura.

---

## 1. Verificare il sistema prima di iniziare

Controllare versione Debian:

`
cat /etc/debian_version
`

Controllare il kernel:

`
uname -a
`

Controllare il driver Mali:

`
dmesg | grep -E 'mali fb000000.gpu: (Kernel DDK|GPU identified|Probed as mali0)'
`

Il kernel funzionante utilizzato nella procedura deve riportare:

`
Kernel DDK version g21p0-01eac0
`

Controllare che il firmware attivo sia quello g21:

`
readlink -f /lib/firmware/mali_csffw.bin
sha256sum /lib/firmware/mali_csffw.bin
`

SHA-256 atteso:

`
8e7c821a55ca1c345cc79f61243616dd25fc35b81f090946f302886d67712df5
`

---

## 2. Verificare che il servizio firmware automatico sia disabilitato

Il servizio set-mali-firmware.service non deve sostituire automaticamente il firmware g21.

`
systemctl is-enabled set-mali-firmware.service
`

Risultato atteso:

`
disabled
`

Se è enabled, fermarsi e verificare la configurazione prima di procedere.

---

## 3. Installare il firmware g21

Il firmware deve essere disponibile in:

`
/lib/firmware/mali_csffw_g21p0/mali_csffw.bin
`

Creare il link al firmware g21:

`
sudo ln -sfn /lib/firmware/mali_csffw_g21p0/mali_csffw.bin \
  /lib/firmware/mali_csffw.bin
`

Verificare:

`
readlink -f /lib/firmware/mali_csffw.bin
sha256sum /lib/firmware/mali_csffw.bin
`

Deve risultare il firmware g21 con SHA-256:

`
8e7c821a55ca1c345cc79f61243616dd25fc35b81f090946f302886d67712df5
`

---

## 4. Backup prima di installare il nuovo userspace

Creare una directory di backup:

`
sudo mkdir -p /root/mali-backup-g24-restore
`

Salvare l'ICD OpenCL eventualmente esistente:

`
if [ -f /etc/OpenCL/vendors/mali-arm64.icd ]; then
    sudo cp -a /etc/OpenCL/vendors/mali-arm64.icd \
      /root/mali-backup-g24-restore/mali-arm64.icd.g13
fi
`

Salvare il firmware g21 come file reale:

`
sudo cp -L /lib/firmware/mali_csffw.bin \
  /root/mali-backup-g24-restore/mali_csffw-g21.bin
`

Verificare il backup:

`
sha256sum /root/mali-backup-g24-restore/mali_csffw-g21.bin
`

---

## 5. Installare il userspace Mali g24p0

Il pacchetto utilizzato nella configurazione funzionante è:

`
libmali-g610-g24p0-x11-wayland-gbm.deb
`

Esempio di percorso:

`
/tmp/libmali-g610-g24p0-x11-wayland-gbm.deb
`

Installare:

`
sudo dpkg -i /tmp/libmali-g610-g24p0-x11-wayland-gbm.deb
`

Il pacchetto installa, tra le altre cose:

- libMaliVulkan.so.1
- libMaliOpenCL.so.1
- mali.json
- configurazione del linker
- firmware Mali

# Importante

Il pacchetto può installare il proprio mali_csffw.bin. Non lasciarlo attivo: il kernel in uso richiede il firmware g21.

---

## 6. Ripristinare immediatamente il firmware g21

Dopo l'installazione del pacchetto:

`
sudo ln -sfn /lib/firmware/mali_csffw_g21p0/mali_csffw.bin \
  /lib/firmware/mali_csffw.bin
`

Verificare:

`
readlink -f /lib/firmware/mali_csffw.bin
sha256sum /lib/firmware/mali_csffw.bin
`

Deve essere:

`
/usr/lib/firmware/mali_csffw_g21p0/mali_csffw.bin
8e7c821a55ca1c345cc79f61243616dd25fc35b81f090946f302886d67712df5
`

---

## 7. Aggiornare la cache del linker

`
sudo ldconfig
`

È possibile che venga mostrato il warning:

`
ldconfig: /lib/librknnrt.so is not a symbolic link
`

Questo warning è indipendente da Mali e non va corretto come parte di questa procedura.

---

## 8. Configurare OpenCL

Il pacchetto g24 deve fornire:

`
/usr/lib/aarch64-linux-gnu/mali/libMaliOpenCL.so.1
`

Controllare:

`
ls -l /usr/lib/aarch64-linux-gnu/mali/libMaliOpenCL.so*
`

Creare l'ICD OpenCL g24:

`
sudo mkdir -p /etc/OpenCL/vendors

echo '/usr/lib/aarch64-linux-gnu/mali/libMaliOpenCL.so.1' | \
  sudo tee /etc/OpenCL/vendors/mali.icd
`

Verificare:

`
cat /etc/OpenCL/vendors/mali.icd
`

Deve contenere esattamente:

`
/usr/lib/aarch64-linux-gnu/mali/libMaliOpenCL.so.1
`

Se è presente il vecchio ICD g13:

`
/etc/OpenCL/vendors/mali-arm64.icd
`

non cancellarlo. Spostarlo nel backup:

`
sudo mv /etc/OpenCL/vendors/mali-arm64.icd \
  /root/mali-backup-g24-restore/mali-arm64.icd.g13
`

In questo modo clinfo vedrà una sola piattaforma ARM proprietaria.

---

## 9. Configurare Vulkan

Verificare che esista:

`
ls -l /usr/share/vulkan/icd.d/mali.json
`

Il contenuto atteso è equivalente a:

`
{
  "file_format_version" : "1.0.0",
  "ICD" : {
    "library_path" : "libMaliVulkan.so.1",
    "api_version" : "1.3.276"
  }
}
`

---

## 10. Verifica OpenCL senza reboot

Eseguire:

`
clinfo | grep -E \
'arm_release_ver|Number of platforms|Platform Version|Device Name'
`

Risultato atteso:

`
arm_release_ver: g24p0-00eac0, rk_so_ver: 10
Number of platforms                               1
Platform Version                                OpenCL 3.0 v1.g24p0-00eac0...
Device Name                                     Mali-G610 r0p0
`

---

## 11. Verifica Vulkan senza dipendere da X11

Per evitare problemi se la sessione grafica X11 non è disponibile:

`
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/mali.json \
vulkaninfo --summary
`

Risultato atteso:

`
driverVersion      = 24.0.0
deviceName         = Mali-G610
driverID           = DRIVER_ID_ARM_PROPRIETARY
driverName         = Mali-G610
apiVersion         = 1.3.276
`

# Nota

Un semplice vulkaninfo --summary può fallire con un errore XCB se non esiste una connessione al server X. In quel caso utilizzare il comando con VK_ICD_FILENAMES mostrato sopra.

---

## 12. Verifica del kernel prima del reboot

`
dmesg | grep -E 'mali fb000000.gpu: (Kernel DDK|Loading Mali firmware|Mali firmware git_sha|GPU identified|Probed as mali0)'
`

Devono essere presenti almeno:

`
Kernel DDK version g21p0-01eac0
GPU identified as 0x7 arch 10.8.6 r0p0 status 0
Probed as mali0
`

Dopo che il firmware è stato utilizzato, deve comparire anche il git SHA g21:

`
Mali firmware git_sha: 221d2b3e5f4cf47df6227ccb24c82c4e4baa986e
`

---

## 13. Riavvio

Prima del reboot verificare:

`
systemctl is-enabled set-mali-firmware.service
readlink -f /lib/firmware/mali_csffw.bin
`

Devono risultare:

`
disabled
/usr/lib/firmware/mali_csffw_g21p0/mali_csffw.bin
`

A questo punto:

`
sudo reboot
`

---

## 14. Verifica dopo il reboot

### Kernel e firmware

`
dmesg | grep -E 'mali fb000000.gpu: (Kernel DDK|Loading Mali firmware|Mali firmware git_sha|GPU identified|Probed as mali0)'
`

Atteso:

`
Kernel DDK version g21p0-01eac0
GPU identified as 0x7 arch 10.8.6 r0p0 status 0
Probed as mali0
`

e, quando il firmware viene inizializzato:

`
Mali firmware git_sha: 221d2b3e5f4cf47df6227ccb24c82c4e4baa986e
`

### Vulkan

`
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/mali.json \
vulkaninfo --summary
`

### OpenCL

`
clinfo | grep -E \
'arm_release_ver|Number of platforms|Platform Version|Device Name'
`

Devono essere presenti:

`
arm_release_ver: g24p0-00eac0, rk_so_ver: 10
Number of platforms                               1
Platform Version                                OpenCL 3.0 v1.g24p0-00eac0...
Device Name                                     Mali-G610 r0p0
`

---

## 15. Verifica finale dei pacchetti

`
dpkg -l | grep -E 'libmali|mali-g610-firmware'
`

Configurazione funzionante di riferimento:

`
libmali-g610-x11
libmali-valhall-g610-g24p0-x11-wayland-gbm
mali-g610-firmware
`

La presenza contemporanea del vecchio pacchetto libmali-g610-x11 non impedisce il funzionamento, purché il vecchio ICD OpenCL g13 non sia attivo.

---

## 16. Rollback

# Non usare apt autoremove per fare rollback.

Se è necessario tornare al precedente userspace g13:

1. Non modificare kernel, DTB o U-Boot.
2. Ripristinare il firmware g21.
3. Ripristinare l'ICD g13.
4. Ripristinare il pacchetto libmali-g610-x11 se necessario.
5. Verificare OpenCL e Vulkan prima di un eventuale reboot.

Ripristino firmware:

`
sudo ln -sfn /lib/firmware/mali_csffw_g21p0/mali_csffw.bin \
  /lib/firmware/mali_csffw.bin
`

Ripristino ICD g13:

`
sudo mv /root/mali-backup-g24-restore/mali-arm64.icd.g13 \
  /etc/OpenCL/vendors/mali-arm64.icd
`

# Nota

Il rollback completo del userspace g13 dipende dal fatto che il relativo .deb sia ancora disponibile. Non rimuovere manualmente librerie a caso: prima verificare lo stato dei pacchetti con dpkg -l.

---

## 17. Stato finale desiderato

La configurazione verificata è:

`
Kernel Mali       g21p0-01eac0
Firmware          g21p0
Userspace Mali    g24p0-00eac0

Vulkan            1.3.276
OpenCL            3.0
GPU               Mali-G610 r0p0
OpenCL platforms  1
`

Questa procedura non richiede modifiche a kernel, DTB o U-Boot.