Debug del sistema: approfondito

Questa sezione andrà un po 'più in profondità nella risoluzione dei problemi, concentrandosi in particolare su un debug di livello più basso con un output di debug appropriato e una configurazione seriale opzionale.

Note: Il 99% degli utenti non ha bisogno di questo livello di debug, questo è solo per casi estremi o estremi.

EFI Setup

Per la maggior parte, sono necessarie modifiche abbastanza minime. Le cose principali che consigliamo sono la versione DEBUG di OpenCore e di tutti i tuoi kexts. Questo può aiutarti a ottenere tutti i dati necessari, vedi qui per maggiori dettagli sul debug di OpenCore: OpenCore debugging

Oltre a utilizzare solo le varianti DEBUG di OpenCore e kexts, anche questi strumenti possono essere di grande aiuto:

Configurazione Config.plist

Per la configurazione seriale, OpenCore lo rende in realtà abbastanza semplice.

Misc

Serial

  • Init: YES
    • Esegue l'inizializzazione della porta seriale
    • Needed for sending OpenCore logging to the serial port

Debug

NVRAM

Argomenti di avvio

Qui possiamo impostare alcune variabili che ci aiuteranno con l'output di debug, per noi utilizzeremo i seguenti argomenti di avvio:

-v keepsyms=1 debug=0x12a msgbuf=1048576

Ora vediamo cosa fa ogni argomento:

  • -v
    • Abilita l'output dettagliato
  • keepsyms=1
    • Assicura che i simboli vengano conservati durante i kernel panic, che sono molto utili per la risoluzione dei problemi
  • debug=0x12a
    • Combinazione di DB_PRT (0x2), DB_PRT (0x8), DB_SLOG (0x20) and and DB_LOG_PI_SCRN (0x100)
    • Un elenco completo dei valori per l'ultima versione di macOS può essere trovato qui: debug.hopen in new window
  • msgbuf=1048576
    • Imposta la dimensione del buffer dei messaggi del kernel, questo aiuta a ottenere i log corretti durante l'avvio
    • 1048576 is 1MB(/1024^2), può essere più grande se necessario
    • Nota non richiesta con DebugEnhancer.kext, tuttavia per i primi log del kernel è ancora richiesta

Altri utili Argomenti di avvio:

A seconda di cosa stai eseguendo il debug, potresti trovare anche questi argomenti di avvio estremamente utili:

  • -liludbgall
    • Abilita il debug su Lilu e qualsiasi altro plugin, tieni presente che anche questo richiede versioni DEBUG di kexts
  • io=0xff
    • Abilita il debug di IOKit, con un output maggiore. Tieni presente che la quantità di registrazione di questo parametro sarà enorme e rallenterà il sistema. Soprattutto durante l'avvio.
  • igdebug=0xff
    • Abilita il debug relativo a iGPU, utile quando si lavora con i sistemi iGPU
  • serial=5
  • acpi_layer=0x8
    • Abilita il debug di ACPI_TABLES, vedi acoutput.hopen in new window per maggiori informazioni
    • 0xFFFFFFFF in alternativa abilita tutti i livelli
  • acpi_level=0x2
    • Imposta il debug di ACPI_LV_DEBUG_OBJECT, vedi acoutput.hopen in new window per maggiori informazioni
    • 0xFFFF5F in alternativa implica "ACPI_ALL_COMPONENTS"

Configurazione del seriale (Opzionale)

Sebbene facoltativo, il seriale può essere molto utile per acquisire tutte le informazioni importanti che invadono il tuo PC. È anche l'unico modo per registrare correttamente i primi kernel panic (come le cose subito dopo [EB | #LOG: EXITBS: START])

Per questa configurazione, avrai bisogno di alcune cose:

  • Una porta seriale sulla macchina che si testa
  • Un cavo da seriale a seriale o da seriale a USB
  • Una seconda macchina per ricevere la registrazione seriale (con seriale o USB)
  • Software per monitorare l'uscita seriale
    • Per questa guida, utilizzeremo CoolTermopen in new window poiché supporta macOS, Linux, Windows e persino Raspberry Pi
      • Anche screen e altri metodi sono supportati.

Hardware Setup

Per questo esempio, utilizzeremo una scheda Asus X299-E Strix che ha una porta seriale. Per verificare se la tua scheda ne ha una, controlla il manuale utente o di servizio e cerca la porta seriale/COM:

Come puoi vedere, abbiamo una porta COM nella parte inferiore della nostra scheda madre e cè anche un diagramma per collegare manualmente i nostri pin seriali se non stai utilizzando un connettore seriale 9/10 pin per l'adattatore DB9.

In alternativa, alcune macchine sono dotate di porte seriali DB9 proprio sull'IO posteriore come questo Dell Optiplex 780 SFF (si noti che VGA e seriale non sono lo stesso connettore):

Per la mia configurazione X299, sto usando un semplice file Serial header to DB9open in new window, e un DB9 to USB RS 232 adapteropen in new window che alla fine termina sul mio laptop:

Serial header to DB9DB9 to USB RS 232 adapter

Il manuale OpenCore generalmente consiglia dispositivi UART basati su CP21202:

Per ottenere il log durante l'avvio è possibile utilizzare il debug della porta seriale. Il debug della porta seriale è abilitato in Target, ad es. 0xB per sullo schermo con seriale. OpenCore utilizza una velocità di trasmissione di 115200, 8 bit di dati, nessuna parità e 1 bit di stop. Per macOS la scelta migliore sono i dispositivi UART basati su CP2102. Collega la scheda madre TX a USB UART RX e la scheda madre GND a USB UART GND. Utilizzare l'utilità dello schermo per ottenere l'output o scaricare il software GUI, come CoolTerm. Nota: su diverse schede madri (e possibilmente su dongle USB UART) la denominazione del PIN potrebbe non essere corretta. È molto comune avere GND scambiato con RX, quindi è necessario collegare la scheda madre "TX" a USB UART GND e la scheda madre "GND" a USB UART RX.

Promemoria importante: non dimenticare di abilitare anche la porta seriale nel BIOS, la maggior parte delle schede madri la disabilita per impostazione predefinita

CoolTerm Setup

Ora avvia CoolTermopen in new window e imposta alcune opzioni. Quando apri CoolTerm, verrai probabilmente accolto con una semplice finestra. Qui seleziona la voce Opzioni:

Qui ci vengono fornite alcune opzioni, ma quelle principali a cui teniamo sono:

  • Port: Assicurati che corrisponda al tuo controller seriale.
  • Baudrate = 115200
  • Data Bits = 8
  • Parity = none
  • Stop Bit = 1

Quindi salvare queste impostazioni e selezionare la voce Connetti. Questo ti fornirà un registro in tempo reale da seriale:

Per registrare, vai semplicemente su Connections -> Capture to Text/Binary File -> Start...(Cmd+R):

Kernel Debug Kits (Opzionale)

I kit di debug del kernel (KDK) sono un ottimo modo per ottenere ancora più informazioni di registrazione dal kernel e dai kext principali, in particolare i KDK sono versioni di debug delle fondamenta di base di macOS fornite da Apple stessa. Includono sia più registrazione che ASSERT che ti consentono di vedere più direttamente i problemi con la tua configurazione. Nota tuttavia non discuteremo del debug con bridge o dell'utilizzo di "lldb".

CAUTION: L'installazione di KDK su macchine da lavoro può portare a problemi con gli aggiornamenti del sistema operativo e corrompere le installazioni. Eseguire il debug su installazioni macOS dedicate per evitare la perdita di dati

Per iniziare, avremo come minimo bisogno di un account sviluppatore gratuitoopen in new window da Apple. Dopo esserti registrato come minimo ad un livello gratuito, ora puoi accedere ai KDK da More Downloads pageopen in new window:

  • Nota: i livelli gratuiti saranno limitati al rilascio di KDK, beta beta di KDKs sono fornite solo ad account sviluppatore a pagamentoopen in new window
  • Nota 2: Apple ospita KDK fin da OS X 10.5, Leopard, quindi non preoccuparti che il tuo sistema operativo non sia supportato.

Per determinare quale build KDK ti serve con le build beta, esegui quanto segue nel terminale:

sw_vers | grep BuildVersion

Per questo, scaricherò il kit di debug del kernel 11.3 build 20E5186d. Una volta scaricato, monta l'immagine del disco e troverai il programma di installazione di KDK. Per impostazione predefinita, il KDK si installerà solo per "Esecuzione del debug su due macchine" e non fornirà alcun vantaggio aggiuntivo sulla macchina host per il debug del kernel per impostazione predefinita.

KDK su un sistema operativo installato

Per abilitare il debug sulla macchina host, dovrai eseguire le seguenti operazioni:

  1. Eseguire KDK Install pkg
  2. Disabilitare SIP(OS X 10.11+)
  3. Montare la partizione di root come scrivibile(macOS 10.15+)
  4. Installa il kernel di debug e kexts
  5. Aggiorna Argomenti di avvio
  6. Riavvia e controlla il tuo lavoro

1. Esegui KDK Install pkg

Esegui semplicemente il pkg come di consueto:

Una volta installati, troverai i componenti KDK come il kernel di debug in /Library/Developer/KDKs:

2. Disabilitare SIP

  • Applicabile a OS X 10.11, El Capitan e più recenti

Per disabilitare SIP, gli utenti hanno 2 scelte:

In genere consigliamo vivamente di usare la Recovery per ripristinare più facilmente tramite il reset NVRAM, tuttavia ad alcuni utenti potrebbe essere richiesto che SIP venga disabilitato anche per effettuare il reset.

Per il primo metodo, riavvia semplicemente in macOS Recovery, apri il terminale ed esegui quanto segue:

csrutil disable
csrutil authenticated-root disable # Big Sur+

Riavvia e SIP sarà stato regolato di conseguenza. Puoi eseguire csrutil status nel terminale per verificare che abbia funzionato.

3. Montare la partizione di root come scrivibile

  • Applicabile for macOS 10.15, Catalina e più recenti

Mounting the root volume as writable is easy, however the process is a bit long:

# Big Sur+
# Innanzitutto, crea un mount point per la tua unità
mkdir ~/livemount

# Quindi, trova il tuo volume di sistema
diskutil list

# Dall'elenco sottostante, possiamo vedere che il nostro volume di sistema è disk5s5
/dev/disk5 (synthesized):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:      APFS Container Scheme -                      +255.7 GB   disk5
                                 Physical Store disk4s2
   1:                APFS Volume ⁨Big Sur HD - Data⁩       122.5 GB   disk5s1
   2:                APFS Volume ⁨Preboot⁩                 309.4 MB   disk5s2
   3:                APFS Volume ⁨Recovery⁩                887.8 MB   disk5s3
   4:                APFS Volume ⁨VM⁩                      1.1 MB     disk5s4
   5:                APFS Volume ⁨Big Sur HD⁩              16.2 GB    disk5s5
   6:              APFS Snapshot ⁨com.apple.os.update-...⁩ 16.2 GB    disk5s5s

# Montare l'unità (es. Disk5s5)
sudo mount -o nobrowse -t apfs  /dev/disk5s5 ~/livemount

# Ora puoi apportare liberamente qualsiasi modifica al volume di sistema

# Solo Catalina
sudo mount -uw /

4. Installa il kernel di debug e kexts

Ora installiamo il nostro KDK nel sistema:

# Installa KDK nel volume di sistema
# Assicurati di sostituire <KDK Version>
# Per 10.15 e versioni precedenti, scambia livemount con /Volumes/<Target Volume>
sudo ditto /Library/Developer/KDKs/<KDK Version>/System ~/livemount/System

# Ricostruisci la cache del kernel (Big Sur e versioni successive)
sudo kmutil install --volume-root ~/livemount --update-all

# Ricostruisci la cache del kernel (Catalina e versioni precedenti)
sudo kextcache -invalidate /Volumes/<Target Volume>

# Infine, una volta terminata la modifica del volume di sistema
# vorremo creare un nuovo snapshot (Big Sur e più recenti)
sudo bless --folder ~/livemount/System/Library/CoreServices --bootefi --create-snapshot

5. Aggiornare Argomenti di avvio

Ora che hai finito di configurare KDK e di averlo installato, dobbiamo dire a boot.efi quale kernel usare. Hai 2 opzioni tra cui scegliere:

  • kcsuffix=debug (removed with Big Sur)
  • kcsuffix=development
  • kcsuffix=kasan

development arg imposterà il nuovo kernel di debug predefinito in Big Sur, mentre kasan è un kernel molto più intensivo di registrazione che incorpora AddressSanitizeropen in new window.

Una volta deciso quale kernel è l'ideale per te, aggiungi l'argomento kcsuffix ai tuoi argomenti di avvio nel tuo config.plist

6. Riavvia e controlla il tuo lavoro

Supponendo che tutto sia stato fatto correttamente, ora vorrai riavviare e verificare che sia stato avviato il kernel corretto:

sysctl kern.osbuildconfig
 kern.osbuildconfig: kasan

E come possiamo vedere, stiamo avviando con successo un kernel KASAN.

Disinstallazione di KDK

La disinstallazione del KDK è abbastanza semplice, tuttavia può essere un po 'distruttiva se non si presta attenzione.

  1. Montare la partizione root come scrivibile (macOS 10.15+)
  2. Rimuovi il kernel di debug e kexts
  3. Riattiva SIP
  4. Ripulire Argomenti di avvio
  5. Riavvia e controlla il tuo lavoro

Steps:

1. Montare la partizione root come scrivibile (macOS 10.15+)

# Big Sur+
# Innanzitutto, crea un mount point per la tua unità
# Salta se ancora presente il volume di montaggio dell'ultima volta
mkdir ~/livemount

# Quindi, trova il tuo volume di sistema
diskutil list

# Dall'elenco sottostante, possiamo vedere che il nostro volume di sistema è disk5s5
/dev/disk5 (synthesized):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:      APFS Container Scheme -                      +255.7 GB   disk5
                                 Physical Store disk4s2
   1:                APFS Volume ⁨Big Sur HD - Data⁩       122.5 GB   disk5s1
   2:                APFS Volume ⁨Preboot⁩                 309.4 MB   disk5s2
   3:                APFS Volume ⁨Recovery⁩                887.8 MB   disk5s3
   4:                APFS Volume ⁨VM⁩                      1.1 MB     disk5s4
   5:                APFS Volume ⁨Big Sur HD⁩              16.2 GB    disk5s5
   6:              APFS Snapshot ⁨com.apple.os.update-...⁩ 16.2 GB    disk5s5s

# Montare l'unità (es. Disk5s5)
sudo mount -o nobrowse -t apfs  /dev/disk5s5 ~/livemount

# Solo Catalina
sudo mount -uw /

2. Rimuovi il kernel di debug e kexts

# Ripristina il precedente snapshot (Big Sur)
sudo bless --mount ~/livemount --bootefi --last-sealed-snapshot

# Reset kernel cache (Catalina e versioni precedenti)
sudo rm /System/Library/Caches/com.apple.kext.caches/Startup/kernelcache.de*
sudo rm /System/Library/PrelinkedKernels/prelinkedkernel.de*
sudo kextcache -invalidate /

3. Riabilitare SIP

  • Comandi da usare in Recovery (se precedentemente modificati tramite Recovery):
csrutil enable
csrutil authenticated-root enable # Big Sur+

4. Ripulire le Argomenti di avvio

Non dimenticare di rimuovere kcsuffix = dalle Argomenti di avvio

5. Riavvia e controlla il tuo lavoro

Supponendo che tutto sia stato fatto correttamente, ora devi riavviare e verificare che sia stato avviato il kernel corretto:

sysctl kern.osbuildconfig
 kern.osbuildconfig: release

E come possiamo vedere, stiamo avviando con successo un kernel KASAN.