## Contributing

Contributi di ogni tipo sono benvenuti, incluse correzioni, chiarimenti, nuovi esempi, traduzioni e revisioni da parte di sviluppatori FreeBSD e studenti.

### Modalità di contribuzione

- **Contenuti:** aggiungere nuovi capitoli, perfezionare il materiale esistente
- **Revisione tecnica:** revisionare i capitoli per accuratezza rispetto a FreeBSD 14.x
- **Revisione delle traduzioni:** aiutare a revisionare e migliorare le edizioni tradotte con IA **pt_BR** e **es_ES**; parlanti nativi con esperienza in FreeBSD/kernel sono particolarmente i benvenuti
- **Nuove traduzioni:** aiutare a tradurre il libro in un'altra lingua
- **Codice:** migliorare esempi, script di build e strumenti
- **Problemi:** segnalare bug, errori fattuali, passaggi poco chiari o problemi di formattazione

### Segnalare un problema

Quando segnali un problema, includi:

- La versione linguistica che stavi leggendo (`en_US`, `pt_BR`, `es_ES`)
- Il formato utilizzato (PDF, EPUB, HTML o Markdown)
- Il capitolo o la sezione in cui appare il problema
- Una breve spiegazione del problema e una correzione suggerita se ne hai una

### Flusso di lavoro

1. Fai il fork del repository
2. Crea un branch: `git checkout -b feature/your-change`
3. Apporta le modifiche e testa la build con `scripts/build-book.sh`
4. Fai un commit con un messaggio chiaro: `git commit -m "Chapter 18: clarify BAR mapping"`
5. Esegui il push e apri una Pull Request

Quando ti blocchi durante la lettura del libro, **segnalare un problema aiuta**. Se un passaggio sembra sbagliato o un laboratorio fallisce inaspettatamente, ogni segnalazione rende il percorso del prossimo lettore più agevole.

## Domande frequenti

### Perché esiste questo libro?

La risposta onesta è che il FreeBSD Project ha bisogno di nuovi contributori, e il percorso verso il lavoro su kernel e driver è sempre stato più ripido di quanto dovrebbe essere. La maggior parte del materiale esistente presuppone che tu conosca già UNIX, che conosca già bene il C, che tu sappia già cos'è un bus e che tu sappia già come leggere un albero dei sorgenti del kernel. Questo funziona per le persone che sono già a buon punto. Fa molto poco per lo sviluppatore curioso che vuole iniziare.

L'obiettivo di questo libro è abbassare quella rampa di accesso. Anche solo un piccolo numero di lettori lo termina e prosegue per inviare patch, revisionare codice, scrivere nuovi driver o eventualmente diventare committer FreeBSD, il libro ha fatto il suo lavoro. **Formare la prossima generazione di contributori FreeBSD è la ragione per cui quest'opera è stata scritta**.

### Devo conoscere C prima di iniziare?

No. I capitoli 4 e 5 insegnano C da zero, concentrandosi sulle parti del linguaggio che contano per il lavoro sul kernel (puntatori, strutture, layout di memoria, preprocessore e convenzioni di chiamata). Se conosci già bene il C, i riquadri in quei capitoli ti dicono cosa sfogliare e cosa leggere attentamente.

### Devo conoscere UNIX o FreeBSD?

No. Il capitolo 2 ti guida nell'installazione di FreeBSD in una VM o su hardware reale, e il capitolo 3 introduce la riga di comando UNIX, il filesystem, i processi, i permessi e gli editor. Alla fine della Parte 1 avrai un laboratorio funzionante e il vocabolario per usarlo.

### Ho bisogno di hardware reale?

Per la maggior parte del libro, no. Una macchina virtuale con FreeBSD 14.x è sufficiente per le basi, i primi capitoli sui driver, la concorrenza e la sincronizzazione, e gran parte del materiale sul debugging. L'hardware reale diventa utile (ma ancora non strettamente necessario) quando si arriva ai capitoli su PCI, interrupt e DMA nella Parte 4. Quei capitoli sono scritti in modo che i concetti abbiano senso anche se li esegui solo in una VM.

### Questo mi aiuterà a scrivere driver Linux?

Indirettamente, sì. La disciplina della programmazione del kernel si trasferisce molto bene: strategia di locking, gestione della memoria, contesto di interrupt, mapping DMA, la differenza tra percorsi di codice bloccanti e non bloccanti, l'ordine di pulizia difensivo. Le API specifiche differiscono. Dopo aver letto questo libro non conoscerai il modello dei dispositivi Linux, ma ne riconoscerai i problemi e la forma delle sue soluzioni, e sarai in grado di leggere Linux Device Drivers (LDD) molto più facilmente.

### Perché proprio FreeBSD 14.x?

Ogni API, ogni esempio e ogni laboratorio sono stati pianificati per essere eseguiti sotto l'albero dei sorgenti di FreeBSD 14.3 e le corrispondenti pagine `man 9`. Prendere di mira una release specifica permette al libro di essere preciso riguardo a firme di funzioni, posizioni degli header e comportamento. I concetti sopravviveranno a 14.x per molti anni; i numeri di riga esatti e i piccoli dettagli delle API non lo faranno, e il libro è onesto al riguardo.

### È una pubblicazione ufficiale del FreeBSD Project?

No. Questo è un libro didattico indipendente sullo sviluppo di driver di dispositivo per FreeBSD. Non è una pubblicazione ufficiale del FreeBSD Project. L'autore è un committer FreeBSD e membro del Documentation Engineering Team (DocEng), ma il libro riflette il suo lavoro e le sue opinioni, non una posizione ufficiale del Progetto.

### Quanto tempo mi ci vorrà effettivamente?

Se leggi attentamente e fai i laboratori, prevedi circa 200 ore di lavoro totale. Sono all'incirca 100 ore di lettura e 100 ore di pratica pratica. A cinque ore a settimana, è un progetto serale di circa sei mesi; a dieci ore a settimana, uno sprint mirato di due mesi. Leggere senza fare i laboratori dimezza il tempo circa, ma dimezza anche il valore: la programmazione del kernel ricompensa la memoria muscolare in un modo che poche discipline fanno.

### Posso saltare i laboratori?

Puoi, ma probabilmente non dovresti. I laboratori sono dove la prosa diventa riflesso. Schemi come l'ordine di associazione, lo svolgimento della pulizia e l'acquisizione dei lock si ripetono in ogni capitolo, e l'unico modo affidabile per interiorizzarli è scriverli, compilarli, caricarli in un kernel in esecuzione e vederli fallire apposta. I lettori che saltano i laboratori riportano progressi che sembrano fluidi all'inizio e poi si fermano silenziosamente intorno alla Parte 3 o Parte 4.

### Come posso contribuire a FreeBSD dopo aver letto questo?

Il capitolo 37 copre l'intero flusso di lavoro di invio: come preparare una patch, come usare Phabricator (il sistema di revisione del codice di FreeBSD), come trovare un committer che sponsorizzi il tuo lavoro, come rispondere al feedback della revisione e come portare un driver nell'albero. I capitoli precedenti costruiscono le competenze tecniche; il capitolo 37 costruisce il flusso di lavoro sociale. Entrambi contano.

### Il libro è enorme. Da dove dovrei iniziare?

Inizia dal capitolo 1 a meno che tu non abbia un motivo per non farlo. Il libro è cumulativo; i capitoli successivi si basano sul vocabolario e sulle abitudini stabiliti in precedenza. Se conosci già C, UNIX e la forma generale di un kernel OS, le note del percorso rapido all'interno della Parte 1 ti dicono cosa sfogliare. Se un sottosistema specifico ti ha portato qui (USB, networking, storage, PCI), va bene leggere attentamente le Parti 1 e 2 e poi saltare avanti, ma aspettati di tornare indietro quando i termini dei capitoli precedenti riappaiono.

### Ho trovato un errore. Cosa dovrei fare?

Apri un problema su GitHub. Includi la versione linguistica, il formato che stavi leggendo, il capitolo o la sezione, una breve descrizione del problema e una correzione suggerita se ne hai una. Ogni segnalazione migliora l'esperienza del prossimo lettore. I problemi di traduzione nelle edizioni pt_BR e es_ES sono particolarmente graditi, poiché non hanno ancora ricevuto una revisione tecnica umana completa.

### Il libro è veramente gratuito?

Sì. È rilasciato sotto licenza MIT. Puoi leggerlo, condividerlo, stamparlo, citarlo, basarti su di esso e tradurlo. L'attribuzione è gradita ma non richiesta per uso personale. Se vuoi supportare il lavoro, le cose più utili che puoi fare sono: parlare del libro ad altre persone, aprire problemi quando trovi errori, contribuire con revisioni o traduzioni e (se alla fine ti ci porta) inviare il tuo lavoro al FreeBSD Project.

## Informazioni sull'autore

Sono Edson Brandi. Il mio percorso nella tecnologia è stato tutt'altro che convenzionale. Ho iniziato come studente di chimica all'Unicamp in Brasile nel 1995, senza alcun piano di lavorare con i computer, ma con una domanda persistente: *come funziona veramente?* Quella domanda mi ha portato a FreeBSD, e FreeBSD ha plasmato la mia carriera da allora.

Negli anni successivi ho fondato il **Brazilian FreeBSD User Group (FUG-BR)**, co-creato il **FreeBSD LiveCD Tool Set**, e nel 2002 co-fondato **FreeBSD Brasil**, un'azienda che fornisce formazione, consulenza e supporto su FreeBSD che opera ancora oggi. Sono un committer FreeBSD e attualmente membro del **FreeBSD Documentation Engineering Team (DocEng)**, aiutando a mantenere i sistemi che mantengono viva e accessibile la documentazione di FreeBSD in tutto il mondo.

Professionalmente, ho trascorso la mia carriera in posizioni di infrastruttura e leadership ingegneristica in diversi settori, e oggi sono IT Director presso una fintech a Londra.

Ho scritto questo libro perché voglio che altre persone curiose abbiano la rampa di accesso che io non ho mai avuto. Non hai bisogno di una laurea in informatica per scrivere codice per il kernel. Quello che ti serve è curiosità, perseveranza, pazienza e una guida che ti incontri dove sei.

Edson Brandi · [email protected]

## Licenza

Questo libro e il suo codice sorgente di accompagnamento sono rilasciati sotto la **Licenza MIT**. Vedi [LICENSE](https://github.com/ebrandi/fdd-book/blob/HEAD/LICENSE) per il testo completo. Sei libero di leggere, condividere e basarti su questo lavoro; l'attribuzione è gradita.

## Riconoscimenti

- La comunità di sviluppo FreeBSD
- Tutti i contributori, revisori e traduttori
- Chiunque abbia mai aperto un problema o fatto una domanda che ha migliorato un capitolo

## Collegamenti

- **Repository:** https://github.com/ebrandi/FDD-book
- **Issues:** https://github.com/ebrandi/FDD-book/issues
- **Discussions:** https://github.com/ebrandi/FDD-book/discussions
- **Author:** Edson Brandi · [email protected]

---

<p align="center"><em>Se questo libro ti aiuta, per favore metti una stella al repository e condividilo con qualcun altro che è curioso di sapere come funzionano davvero i computer.</em></p>