Le guide de l'auteur de pilotes de périphériques pour FreeBSD

3.1.1. Structures de données

Structure cdevsw

3.1.2. Points d'entrée

int
d_open(dev_t dev, int flag, int mode, struct proc *p)

int
d_close(dev_t dev , int flag , int mode , struct proc *p)

 ...
    fd1=open("/dev/mydev", O_RDONLY);
    fd2=open("/dev/mydev", O_RDONLY);
    fd3=open("/dev/mydev", O_RDONLY);
 ...
   <useful stuff with fd1, fd2, fd3 here>
 ...
    close(fd1);
    close(fd2);
    close(fd3);
 ...

int
d_read(dev_t dev, struct uio *uio, int flat)
int
d_write(dev_t dev, struct uio *uio, int flat)

int
d_ioctl(dev_t dev, int cmd, caddr_t arg, int flag, struct proc *p)

void
d_poll(dev_t dev, int events, struct proc *p)

static struct my_softc {
        struct queue rx_queue;  /* As example only - not required */
        struct queue tx_queue;  /* As example only - not required */
        struct selinfo selp;    /* Required */
} my_softc[NMYDEV];

...

static int
mydevpoll(dev_t dev, int events, struct proc *p)
{
        int revents = 0;        /* Events we found */
        int s;
        struct my_softc *sc = &my_softc[dev];

        /* We can only check for IN and OUT */
        if ((events & (POLLIN|POLLOUT)) == 0)
                return(POLLNVAL);

        s = splhigh();
        /* Writes are if the transmit queue can take them */
        if ((events & POLLOUT) &&
            !IF_QFULL(sc->tx_queue))
                revents |= POLLOUT;
        /* ... while reads are OK if we have any data */
        if ((events & POLLIN) &&
            !IF_QEMPTY(sc->rx_queue))
                revents |= POLLIN;
        if (revents == 0)
                selrecord(p, &sc->selp);
        splx(s);
        return revents;
}

static int
mydevselect(dev_t dev, int rw, struct proc *p)
{
        int ret = 0;
        int s;
        struct my_softc *sc = &my_softc[dev];

        s = splhigh();
        switch (rw) {
        case FWRITE:
                /* Writes are if the transmit queue can take them */
                if (!IF_QFULL(sc->tx_queue))
                        ret = 1;
                break;
        case FREAD:
                /* ... while reads are OK if we have any data */
                if (!IF_QEMPTY(sc->rx_queue))
                        ret = 1;
                break;
        case 0:
                /* This driver never get any exceptions */
                break;
        }
        if(ret == 0)
                selrecord(p, &sc->selp);
        splx(s);
        return(revents);
}

void
d_strategy(struct buf *bp)

3.1.3. Fichiers d'en-tête

3.2.1. Structures de données

Structure struct bdevsw

Structure struct buf

3.2.2. Points d'entrée

3.2.3. Fichiers d'en-tête

3.3.1. Points d'entrée

3.3.2. Fichiers d'en-tête

3.4.1. Structures de données

Structure struct linesw

3.4.2. Points d'entrée

3.4.3. Fichiers d'en-tête

4.1.1. Structures de données

struct isa_device {
        int     id_id;          /* device id */
        struct  isa_driver *id_driver;
        int     id_iobase;      /* base i/o address */
        u_short id_irq;         /* interrupt request */
        short   id_drq;         /* DMA request */
        caddr_t id_maddr;       /* physical i/o memory address on bus (if any)*/
        int     id_msize;       /* size of i/o memory */
        inthand2_t *id_intr;    /* interrupt interface routine */
        int     id_unit;        /* unit number */
        int     id_flags;       /* flags */
        int     id_scsiid;      /* scsi id if needed */
        int     id_alive;       /* device is present */
#define RI_FAST         1               /* fast interrupt handler */
        u_int   id_ri_flags;    /* flags for register_intr() */
        int     id_reconfig;    /* hot eject device support (such as PCMCIA) */
        int     id_enabled;     /* is device enabled */
        int     id_conflicts;   /* we're allowed to conflict with things */
        struct isa_device *id_next; /* used in isa_devlist in userconfig() */
};

struct isa_driver { 
        int     (*probe) __P((struct isa_device *idp));
                                        /* test whether device is present */
        int     (*attach) __P((struct isa_device *idp));
                                        /* setup driver for a device */
        char    *name;                  /* device name */
        int     sensitive_hw;           /* true if other probes confuse us */
};

struct  isa_driver      mcddriver = { mcd_probe, mcd_attach, "mcd" };

4.1.2. Points d'entrée

4.1.3. Fichiers d'en-tête

4.2.1. Structures de données

Structure struct eisa_dev

Structure struct isa_driver

4.2.2. Points d'entrée

4.2.3. Fichiers d'en-tête

4.3.1. Structures de données

Structure struct pci_device

• nom : Le nom abrégé du périphérique.

• sonde: Contrôle si le pilote peut supporter un périphérique avec ce type. L'étiquette peut être employée pour obtenir plus d'information avec pci_read_conf(). Voir ci-dessous. Elle renvoie une chaîne de caractères avec le nom du périphérique, ou un pointeur NULL si le pilote ne peut pas supporter ce périphérique.

• attache: Assigne une structure de contrôle et la prépare. Cette fonction peut utiliser les fonctions de mapping PCI. Voir ci-dessous. (identification de configuration) ou type.

• compte: Un pointeur sur un compteur d'unité. Il est employé par le configurateur de PCI pour assigner des numéros.

4.3.2. Points d'entrée

4.3.3. Fichiers d'en-tête

4.4.1. Structure de données

Structure struct scsi_adapter

Structure struct scsi_device

Structure struct scsi_ctlr_config

Structure struct scsi_device_config

Structure struct scsi_link

4.4.2. Points d'entrée

4.4.3. Fichiers d'en-tête

4.5.1. Structure de données

Structure struct slot_cont

Structure struct pccard_drv

Structure struct pccard_dev

Structure struct slot

4.5.2. Points d'entrée

4.5.3. Fichiers d'en-tête

<pccard/slot.h>

5.1.1. Ajout à la liste des pilotes de périphérique

Le modèle standard pour ajouter un module de gestion de périphérique au noyau de Berkeley est d'ajouter votre pilote à la liste des périphériques connus. Cette liste dépend de l'architecture du CPU. Si le périphérique n'est pas spécifique i386 (PCCARD, PCI, SCSI), le fichier est dans /usr/src/sys/conf/files. Si le périphérique est spécifique i386, utilisez /usr/src/sys/i386/conf/files.i386. Une ligne typique ressemblerait à :

i386/isa/joy.c                  optional        joy     device-driver

Le premier champ relatif est le chemin du module de pilote par rapport à /usr/src/sys. Pour le cas d'un pilote binaire, le chemin d'accès serait quelque chose comme i386/OBJ/joy.o.

Le deuxième champ indique à config(8) que c'est un pilote facultatif. Quelques périphériques sont obligatoires pour que le noyau puisse être construit.

Le troisième champ est le nom du périphérique.

Le quatrième champ indique à config que c'est un pilote de périphérique (par opposition à juste facultatif). Ceci dit à config de créer des entrées pour le périphérique dans dans des structures de /usr/src/sys/compile/KERNEL/ioconf.c.

Il est également possible de créer un fichier /usr/src/sys/i386/conf/files.KERNEL dont le contenu ignorera le fichier par défaut files.i386, mais seulement pour le noyau ``KERNEL''.

5.1.2. Faire de la place dans conf.c

Maintenant vous devez éditer /usr/src/sys/i386/i386/conf.c pour faire une entrée pour votre pilote. Quelque part au début, vous devez déclarer vos points d'entrée. L'entrée pour le pilote du joystick est:

#include "joy.h" 
#if NJOY > 0
d_open_t        joyopen;
d_close_t       joyclose;
d_rdwr_t        joyread;
d_ioctl_t       joyioctl;
#else
#define joyopen         nxopen
#define joyclose        nxclose
#define joyread         nxread
#define joyioctl        nxioctl
#endif

Cela définit vos points d'entrée, ou points d'entrée nuls qui renverront ENXIO quand appelé (clause #else).

Le fichier d'en-tête ``joy.h'' est automatiquement produit par config quand l'arborescence de construction du noyau est créé. Cela se réduit habituellement à une seule ligne comme :

#define NJOY 1

ou

#define NJOY 0

ce qui définit le nombre de vos périphériques dans votre noyau.

Vous devez de plus ajouter un slot au cdevsw[], ou au bdevsw[], selon que ce soit un périphérique caractère, périphérique bloc, ou les deux si c'est un périphérique bloc avec une interface brute. L'entrée pour le pilote du joystick est:

/* open, close, read, write, ioctl, stop, reset, ttys, select, mmap, strat */
struct cdevsw   cdevsw[] =
{
 ...
        { joyopen,      joyclose,       joyread,        nowrite, /*51*/
          joyioctl,     nostop,         nullreset, nodevtotty,/*joystick */
          seltrue,      nommap,         NULL},
 ...
}

L'ordre est ce qui détermine le nombre majeur de votre périphérique. C'est pourquoi il y aura toujours une entrée pour votre pilote, que ce soit des points d'entrée nuls, ou des points d'entrée actuels. Il est probablement intéressant de noter que c'est sensiblement différent de SCO et d'autres dérivés du système V, où n'importe quel périphérique (dans la théorie) peut avoir n'importe quel nombre majeur. C'est en grande partie un avantage sur FreeBSD, sur la manière dont les fichiers spéciaux de périphérique sont créés. Nous reviendrons en détail sur ceci plus tard.

5.1.3. Ajout de votre périphérique dans le fichier de configuration.

Ceci ajoute simplement une ligne décrivant votre périphérique. La ligne de description du joystick est :

device          joy0    at isa? port "IO_GAME"

Une entrée légèrement plus compliquée est pour le pilote ``ix'' :

device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768
vector ixintr

5.1.4. config du noyau.

Maintenant avec notre fichier de configuration en main, nous pouvons créer un répertoire de compilation du noyau. Cela peut être fait en tapant :

# config KERNEL

Maintenant vous pouvez aller dans le répertoire de compilation et construire votre noyau. À chaque fois que vous lancerez config, votre arbre de construction précédent sera retiré, à moins que vous ne lancez config avec un -n. Si vous avez configuré et compilé un noyau GENERIC, vous pouvez faire un ``make links'' afin d'éviter de compiler certains fichiers à chaque itération. Typiquement, je lance :

  
# make depend links all

5.1.5. Créer les fichiers spéciaux de périphériques

Sur FreeBSD, vous avez la responsabilité de faire vos propres fichiers spéciaux de périphérique. Le nombre majeur de votre périphérique est déterminé par le nombre de slots dans le commutateur de périphérique. Le nombre mineur est dépendant du pilote, naturellement. Vous pouvez soit exécuter mknod depuis la ligne de commande, soit laisser faire le travail à /dev/MAKEDEV.local, ou même /dev/MAKEDEV. Je crée parfois un script MAKEDEV.dev qui peut être soit lancé de manière autonome soit collé dans /dev/MAKEDEV.local.

5.1.6. Redémarrage

C'est la partie facile. Il y a un certain nombre de méthodes pour faire ceci, reboot, fastboot, shutdown - r, couper le courant, etc. Au démarrage, vous devriez voir votre XXprobe() appelé, et si tout marche, votre attach() aussi.

5.3.1. Caractère

5.3.2. Bloc

5.3.3. Réseau

5.3.4. Line discipline

5.4.1. ISA

5.4.2. EISA

5.4.3. PCI

5.4.4. SCSI

5.4.5. PCCARD

6.1.1. Structure struct kern_devconf

Cette structure contient quelques informations sur l'état du périphérique et de son pilote. Elle est définie dans /usr/src/sys/sys/devconf.h comme ci-dessous :

struct devconf {
        char dc_name[MAXDEVNAME];       /* name */
        char dc_descr[MAXDEVDESCR];     /* description */
        int dc_unit;                    /* unit number */
        int dc_number;                  /* unique id */
        char dc_pname[MAXDEVNAME];      /* name of the parent device */
        int dc_punit;                   /* unit number of the parent */
        int dc_pnumber;                 /* unique id of the parent */
        struct machdep_devconf dc_md;   /* machine-dependent stuff */
        enum dc_state dc_state;         /* state of the device (see above) */
        enum dc_class dc_class;         /* type of device (see above) */
        size_t dc_datalen;              /* length of data */
        char dc_data[1];                /* variable-length data */
};

6.1.2. Structure struct proc

Cette structure contient toutes les informations sur un processus. Elle est dans définie /usr/src/sys/sys/proc.h:

/*
 * Description of a process.
 *
 * This structure contains the information needed to manage a thread of
 * control, known in UN*X as a process; it has references to
substructures
 * containing descriptions of things that the process uses, but may
share
 * with related processes.  The process structure and the substructures
 * are always addressable except for those marked "(PROC ONLY)" below,
 * which might be addressable only on a processor on which the process
 * is running.
 */
struct  proc {
        struct  proc *p_forw;           /* Doubly-linked run/sleep queue. */
        struct  proc *p_back;
        struct  proc *p_next;           /* Linked list of active procs */
        struct  proc **p_prev;          /*    and zombies. */

        /* substructures: */
        struct  pcred *p_cred;          /* Process owner's identity. */
        struct  filedesc *p_fd;         /* Ptr to open files structure.  */
        struct  pstats *p_stats;        /* Accounting/statistics (PROC ONLY). */
        struct  plimit *p_limit;        /* Process limits. */
        struct  vmspace *p_vmspace;     /* Address space. */
        struct  sigacts *p_sigacts;     /* Signal actions, state (PROC ONLY). */

#define p_ucred         p_cred->pc_ucred
#define p_rlimit        p_limit->pl_rlimit

        int     p_flag;                 /* P_* flags. */
        char    p_stat;                 /* S* process status. */
        char    p_pad1[3];

        pid_t   p_pid;                  /* Process identifier. */
        struct  proc *p_hash;    /* Hashed based on p_pid for kill+exit+... */
        struct  proc *p_pgrpnxt; /* Pointer to next process in process group. */
        struct  proc *p_pptr;    /* Pointer to process structure of parent. */
        struct  proc *p_osptr;   /* Pointer to older sibling processes.  */

/* The following fields are all zeroed upon creation in fork. */
#define p_startzero     p_ysptr
        struct  proc *p_ysptr;   /* Pointer to younger siblings. */
        struct  proc *p_cptr;    /* Pointer to youngest living child. */
        pid_t   p_oppid;         /* Save parent pid during ptrace. XXX */
        int     p_dupfd;         /* Sideways return value from fdopen.  XXX */

        /* scheduling */
        u_int   p_estcpu;        /* Time averaged value of p_cpticks. */
        int     p_cpticks;       /* Ticks of cpu time. */
        fixpt_t p_pctcpu;        /* %cpu for this process during p_swtime */
        void    *p_wchan;        /* Sleep address. */
        char    *p_wmesg;        /* Reason for sleep. */
        u_int   p_swtime;        /* Time swapped in or out. */
        u_int   p_slptime;       /* Time since last blocked. */

        struct  itimerval p_realtimer;  /* Alarm timer. */
        struct  timeval p_rtime;        /* Real time. */
        u_quad_t p_uticks;              /* Statclock hits in user mode.  */
        u_quad_t p_sticks;              /* Statclock hits in system mode. */
        u_quad_t p_iticks;              /* Statclock hits processing intr. */

        int     p_traceflag;            /* Kernel trace points. */
        struct  vnode *p_tracep;        /* Trace to vnode. */

        int     p_siglist;              /* Signals arrived but not delivered. */

        struct  vnode *p_textvp;        /* Vnode of executable. */

        char    p_lock;                 /* Process lock (prevent swap) count. */
        char    p_pad2[3];              /* alignment */

/* End area that is zeroed on creation. */
#define p_endzero       p_startcopy

/* The following fields are all copied upon creation in fork. */
#define p_startcopy     p_sigmask

        sigset_t p_sigmask;     /* Current signal mask. */
        sigset_t p_sigignore;   /* Signals being ignored. */
        sigset_t p_sigcatch;    /* Signals being caught by user. */

        u_char  p_priority;     /* Process priority. */
        u_char  p_usrpri;       /* User-priority based on p_cpu and p_nice. */
        char    p_nice;         /* Process "nice" value. */
        char    p_comm[MAXCOMLEN+1];

        struct  pgrp *p_pgrp;   /* Pointer to process group. */

        struct  sysentvec *p_sysent; /* System call dispatch information. */

        struct  rtprio p_rtprio;        /* Realtime priority. */
/* End area that is copied on creation. */
#define p_endcopy       p_addr
        struct  user *p_addr;   /* Kernel virtual addr of u-area (PROC ONLY). */
        struct  mdproc p_md;    /* Any machine-dependent fields. */

        u_short p_xstat;        /* Exit status for wait; also stop signal. */
        u_short p_acflag;       /* Accounting flags. */
        struct  rusage *p_ru;   /* Exit information. XXX */
};

6.1.3. Structure struct buf

La structure struct buf est employée pour s'interfacer avec le cache de la mémoire tampon. Elle est dans définie /usr/src/sys/sys/buf.h :

/*
 * The buffer header describes an I/O operation in the kernel.
 */
struct buf {
        LIST_ENTRY(buf) b_hash;         /* Hash chain. */
        LIST_ENTRY(buf) b_vnbufs;       /* Buffer's associated vnode. */
        TAILQ_ENTRY(buf) b_freelist;    /* Free list position if not active. */
        struct  buf *b_actf, **b_actb;  /* Device driver queue when active. */
        struct  proc *b_proc;           /* Associated proc; NULL if kernel. */
        volatile long   b_flags;        /* B_* flags. */
        int     b_qindex;               /* buffer queue index */
        int     b_error;                /* Errno value. */
        long    b_bufsize;              /* Allocated buffer size. */
        long    b_bcount;               /* Valid bytes in buffer. */
        long    b_resid;                /* Remaining I/O. */
        dev_t   b_dev;                  /* Device associated with buffer. */
        struct {
                caddr_t b_addr;         /* Memory, superblocks, indirect etc. */
        } b_un;
        void    *b_saveaddr;            /* Original b_addr for physio.  */
        daddr_t b_lblkno;               /* Logical block number. */
        daddr_t b_blkno;                /* Underlying physical block number. */
                                        /* Function to call upon completion. */
        void    (*b_iodone) __P((struct buf *));
                                        /* For nested b_iodone's. */
        struct  iodone_chain *b_iodone_chain;
        struct  vnode *b_vp;            /* Device vnode. */
        int     b_pfcent;               /* Center page when swapping cluster. */
        int     b_dirtyoff;             /* Offset in buffer of dirty region. */
        int     b_dirtyend;             /* Offset of end of dirty region. */
        struct  ucred *b_rcred;         /* Read credentials reference.  */
        struct  ucred *b_wcred;         /* Write credentials reference.  */
        int     b_validoff;             /* Offset in buffer of valid region. */
        int     b_validend;             /* Offset of end of valid region. */
        daddr_t b_pblkno;               /* physical block number */
        caddr_t b_savekva;              /* saved kva for transfer while bouncing */
        void    *b_driver1;             /* for private use by the driver */
        void    *b_driver2;             /* for private use by the driver */
        void    *b_spc;
        struct  vm_page *b_pages[(MAXPHYS + PAGE_SIZE - 1)/PAGE_SIZE];
        int             b_npages;
};

6.1.4. Structure struct uio

Cette structure est utilisée pour déplacer des données entre le noyau et les espaces utilisateur par les appels système de read() et de write(). Il est dans défini /usr/src/sys/sys/uio.h :

struct uio {
        struct  iovec *uio_iov;
        int     uio_iovcnt;
        off_t   uio_offset;
        int     uio_resid;
        enum    uio_seg uio_segflg;
        enum    uio_rw uio_rw;
        struct  proc *uio_procp;
};