Le HOWTO Linux de la programmation SCSI

Heiko Eißfeldt heiko@colossus.escape.de (version fran�aise : Thierry Danis thierry.danis@hol.fr, le 26 Janvier 1998, largement bas�e sur la traduction de la version v1.4 faite par Bernard Choppy choppy@imaginet.fr).

v1.5, 7 Juin 1996
Ce document traite de la programmation de l'interface SCSI g�n�rique de Linux.

Appendix

1. Les nouveaut�s

Les interfaces des nouveaux noyaux ont un peu chang�. Le chapitre 'rescrutation des p�riph�riques' est concern� par ces changements. Il est maintenant possible d'ajouter et d'enlever des p�riph�riques SCSI � chaud et � la vol�e.

A partir de la version 1.3.98, certains fichiers d'inclusion importants ont �t� d�plac�s ou d�coup�s (sg.h and scsi.h).

Quelques bugs idiots ont �t� remplac�s par d'autres.

2. Introduction

Ce document est un guide d'installation et de programmation de l'interface g�n�rique SCSI de Linux.

Il traite des pr�requis du noyau, de l'organisation des p�riph�riques, et de l'interaction de base avec ces derniers. Quelques exemples simples de programmation en C sont inclus. Pour de plus amples d�tails sur la norme SCSI et les informations associ�es, reportez-vous � l'annexe de ce document.

Note : la version texte simple de ce document ne dispose pas de r�f�r�nces crois�es (indiqu�es par ``'').

3. Qu'est-ce que l'interface SCSI g�n�rique ?

L'interface g�n�rique SCSI a �t� faite pour fournir un acc�s g�n�ral � des p�riph�riques SCSI (�ventuellement exotiques). Elle a �t� d�velopp�e par Lawrence Foard ( entropy@world.std.com) et sponsoris�e par Killy Corporation (voir les commentaires du fichier drivers/scsi/sg.h).

Cette interface permet � des programmes applicatifs (c'est-�-dire hors du noyau) d'acc�der aux fonctionnalit�s de certains p�riph�riques. Le d�veloppement de pilotes dans le noyau, plus risqu�s et difficiles � mettre au point, n'est ainsi plus n�cessaire.

N�anmoins, si le p�riph�rique n'est pas correctement programm�, il est possible de bloquer le bus SCSI, le pilote, ou le noyau. C'est pourquoi il est important de programmer correctement le pilote g�n�rique, et de commencer par sauvegarder tous les fichiers afin d'�viter une perte de donn�es. Une autre pr�caution utile est de faire un sync avant de lancer vos programmes pour garantir l'�criture de tous les tampons sur le disque ; cela limitera la perte de donn�es en cas de blocage du syst�me.

Un autre avantage du pilote g�n�rique est que, aussi longtemps que l'interface elle-m�me ne change pas, toutes les applications restent ind�pendantes des nouveaux d�veloppements du noyau. En comparaison, les pilotes de bas niveau du noyau doivent suivre les �volutions internes de celui-ci.

Typiquement, le pilote g�n�rique est utilis� pour communiquer avec les nouveaux �quipements SCSI qui exigent l'�criture d'applications utilisateur sp�cifiques pour tirer avantage de leurs fonctionalit�s (par exemple les scanners, les imprimantes, le juke-boxes de CDROM). L'interface g�n�rique permet un d�veloppement rapide de ces applications.

4. Que faut-il pour l'utiliser ?

4.1 Configuration du noyau

Il vous faut �videmment un adapteur SCSI reconnu. De plus, votre noyau doit �tre compil� avec le support du pilote g�n�rique, en plus de celui pour votre adapteur. La configuration du noyau Linux (par make config sous /usr/src/linux) doit ressembler � :

 ...
*
* SCSI support
*
SCSI support? (CONFIG_SCSI) [n] y
*
* SCSI support type (disk, tape, CDrom)
*
 ...
Scsi generic support (CONFIG_CHR_DEV_SG) [n] y
*
* SCSI low-level drivers
*
 ...

Si le noyau est modulable, vous pouvez tout aussi bien utiliser les modules.

4.2 Fichiers sp�ciaux

Le pilote g�n�rique utilise ses propres fichiers sp�ciaux. Ils peuvent �tre cr��s par le script MAKEDEV, que l'on trouve habituellement dans le r�pertoire /dev. La commande MAKEDEV sg cr�e les fichiers suivants :

crw-------   1 root     system    21,   0 Aug 20 20:09 /dev/sga
crw-------   1 root     system    21,   1 Aug 20 20:09 /dev/sgb
crw-------   1 root     system    21,   2 Aug 20 20:09 /dev/sgc
crw-------   1 root     system    21,   3 Aug 20 20:09 /dev/sgd
crw-------   1 root     system    21,   4 Aug 20 20:09 /dev/sge
crw-------   1 root     system    21,   5 Aug 20 20:09 /dev/sgf
crw-------   1 root     system    21,   6 Aug 20 20:09 /dev/sgg
crw-------   1 root     system    21,   7 Aug 20 20:09 /dev/sgh
                                   |    |
                       num�ros majeur, mineur

Notez que ces fichiers sont des fichiers en mode caract�re pour permettre les acc�s directs. Sur certains syst�mes, ces fichiers peuvent s'appeler /dev/{sg0,sg1,...}, en fonction de votre installation. Vous devrez donc adapter les exemples qui suivant en cons�quence.

4.3 Organisation des p�riph�riques

Les fichiers sp�ciaux sont affect�s dynamiquement aux ID/LUN (LUN : Unit� logique) du bus SCSI. Les p�riph�riques sont cons�cutivement allou�s selon les unit�s logiques de chaque p�riph�rique d�tect� lors de la scrutation du bus, les plus petits LUN/ID/BUS �tant allou�s en premier. Le noyau commence par le premier contr�leur SCSI et continue sans interruption avec tous les autres adapteurs. Cette �tape est actuellement r�alis�e lors de l'initialisation du pilote SCSI.

Par exemple, si vous avez trois p�riph�riques SCSI configur�s avec les ID 1, 3 et 5 sur le premier bus SCSI (chacun avec une seule unit� logique), l'affectation sera la suivante :

/dev/sga -> SCSI id 1
/dev/sgb -> SCSI id 3
/dev/sgc -> SCSI id 5

Si vous ajoutez maintenant un nouveau p�riph�rique d'identificateur 4, l'organisation apr�s la prochaine scrutation du bus sera :

/dev/sga -> SCSI id 1
/dev/sgb -> SCSI id 3
/dev/sgc -> SCSI id 4
/dev/sgd -> SCSI id 5

Notez le changement pour l'identificateur 5 - le p�riph�rique correspondant n'est plus affect� � /dev/sgc, mais � /dev/sgd.

Les noyaux plus r�cents permettent de changer cet ordre.

Insertion et retrait dynamiques de p�riph�riques SCSI

Dans les noyaux r�cents avec un syst�me de fichier /proc mont�, il est possible de retirer et d'ajouter un p�riph�rique libre (non-busy) � la vol�e.

Pour enlever un p�riph�rique SCSI :

echo "scsi remove-single-device a b c d" > /proc/scsi/scsi

De la m�me mani�re, ajouter un p�riph�rique SCSI se fera par :

echo "scsi add-single-device a b c d" > /proc/scsi/scsi

Ici, a, b, c et d sont d�finis de la fa�on suivante :

      a == identificateur de l'adapteur (le premier a l'id 0)
      b == canal SCSI sur l'adapteur (le premier a le num�ro 0)
      c == ID
      d == LUN (la premi�re ayant le num�ro 0)

Ainsi, si nous d�sirons intervertir l'affectation des fichiers /dev/sgc et /dev/sgd de l'exemple pr�c�dent, nous pouvons faire :

echo "scsi remove-single-device 0 0 4 0" > /proc/scsi/scsi
echo "scsi remove-single-device 0 0 5 0" > /proc/scsi/scsi
echo "scsi add-single-device 0 0 5 0" > /proc/scsi/scsi
echo "scsi add-single-device 0 0 4 0" > /proc/scsi/scsi

puisque les p�riph�riques g�n�riques sont allou�s dans leur ordre d'insertion.

Si vous voulez ajouter de nouveaux p�riph�riques sur le bus SCSI, gardez � l'esprit qu'un nombre limit� d'entr�es suppl�mentaires a �t� attribu�. La m�moire a �t� allou�e au d�marrage, et il n'y a de place que pour 2 entr�es suppl�mentaires.

5. Le guide du programmeur

Les sections qui suivent s'adressent aux programmeurs d�sireux d'utiliser l'interface g�n�rique SCSI dans leurs propres applications. Nous allons donner un exemple permettant d'acc�der � un p�riph�rique SCSI par le biais des commandes INQUIRY et TESTUNITREADY.

Lors de l'utilisation de ces exemples, prenez garde � ce qui suit :

6. Vue d'ensemble de la programmation des p�riph�riques

Le fichier d'inclusion include/scsi/sg.h contient une description de l'interface (celle du noyau 1.3.98) :

struct sg_header
 {
                        /*
                         * longueur du paquet entrant (y compris en-t�te)
                         */
  int pack_len;
                        /*
                         * taille max de la r�ponse attendue
                         */
  int reply_len;
                        /*
                         * num�ro d'id du paquet
                         */
  int pack_id;
                        /*
                         * 0 == ok,
                         * pour les autres, voir les codes pour errno
                         */
  int result;
                        /*
                         * Force la longueur a 12 pour les commandes des
                         * groupes 6 & 7
                         */
  unsigned int twelve_byte:1;
                        /*
                         * pour utilisation future
                         */
  unsigned int other_flags:31;
                        /*
                         * uniquement utilis� lors des lectures
                         */
  unsigned char sense_buffer[16];
                        /*
                         * la commande suit puis les donn�es de la
                         * commande
                         * .............
                         */

Cette structure d�crit comment une commande SCSI doit �tre trait�e et disposer de place pour le r�sultat de son ex�cution. Les composants individuels de la structure seront abord�s plus loin � la section La structure d'en-t�te.

La m�thode g�n�rale pour �changer des donn�es avec le pilote g�n�rique est la suivante : pour envoyer une commande � un p�riph�rique g�n�rique ouvert, il faut �crire (write()) un bloc compos� des trois parties suivantes :

                             struct sg_header
                               commande SCSI
                     donn�es envoy�es avec la commande

Pour obtenir le r�sultat d'une commande, il faut lire (read()) un bloc compos�s des parties suivantes (similaires � l'�criture) :

                             struct sg_header
                             donn�es en entr�e

Il s'agit d'une vue g�n�rale de la proc�dure. Les sections qui suivent d�crivent chaque �tape en d�tail.

NOTE : jusqu'� de r�centes versions du noyau, il �tait n�cessaire de bloquer le signal SIGINT entre les appels write() et le read() correspondant (par exemple, par sigprocmask()). Un retour apr�s la partie �criture sans lecture pour r�cup�rer les r�sultats va bloquer les acc�s suivants. Le blocage du signal n'a pas encore �t� inclus dans le code des exemples. Evitez donc d'envoyer un SIGINT (par ^C, par exemple) lors du test de ceux-ci.

7. Ouverture du p�riph�rique

Un p�riph�rique g�n�rique doit �tre ouvert avant tout acc�s en lecture ou en �criture :

        int fd = open(nom_du_p�riph�rique, O_RDWR);

(ce qui pr�c�de s'applique aussi pour les mat�riels en lecture seule comme les lecteurs de CDROM).

Il faut ex�cuter un write pour envoyer la commande et un read pour en lire le r�sultat. En cas d'erreur, le code de retour est n�gatif (se reporter � la section Traitement d'erreurs pour la liste compl�te des codes de retour).

8. La structure d'en-t�te

La structure d'en-t�te struct sg_header est utilis�e comme couche de contr�le entre l'application et le pilote du noyau. Abordons maintenant le d�tail de ses composants.

int pack_len

d�finit la taille du bloc envoy� au pilote. Cette valeur est d�finie dans le noyau pour une utilisation interne.

int reply_len

d�finit la taille du bloc accept� en r�ponse. Cette valeur est d�finie du c�t� application.

int pack_id

Ce champ facilite l'appariement des r�ponses aux requ�tes. L'application peut fournir un identifiant unique � chaque requ�te. Supposons que vous ayez �crit un certain nombre de commandes (disons 4) pour un p�riph�rique. Celles-ci peuvent fonctionner en parall�le, l'une d'entre elles �tant la plus rapide. Lors de la lecture des r�ponses par quatre "read", celles-ci ne sont pas forc�ment dans l'ordre des requ�tes. Pour identifier la r�ponse correcte pour une requ�te, on peut utiliser le champ pack_id. Habituellement, cette valeur est incr�ment�e apr�s chaque requ�te (et boucle �ventuellement). Le nombre maximum de requ�tes �mises simultan�ment est limit� par le noyau � SG_MAX_QUEUE (en g�n�ral, quatre).

int result

C'est la valeur du r�sultat d'un appel � read ou � write. Elle est (parfois) d�finie par la le pilote g�n�rique (partie noyau). Il est plus prudent de le positionner � 9 avant l'appel � write. Ces codes sont d�clar�s dans le fichier errno.h (0 indique un r�sultat correct).

unsigned int twelve_byte:1

Ce champ n'est n�cessaire que lors de l'utilisation de commandes sp�cifiques non standard (dans la plage 0xc0 � 0xff). Lorsque la longueur de ces commandes est de 12 octets au lieu de 10, il faut positionner ce champ � 1 avant l'appel � write. D'autres longueurs de commandes ne peuvent �tre utilis�es. Ce champ est positionn� par l'application.

unsigned char sense_buffer[16]

Ce tampon est positionn� apr�s l'ex�cution d'une commande (apr�s un appel � read()) et contient le code de "sensation" SCSI (SCSI send code. NdT. : dans le reste du document, on utilisera simplement la formule "tampon SCSI"). Certains r�sultats de commandes doivent �tre lus � cet emplacement (par exemple pour TESTUNITREADY). Il ne contient habituellement que des octets nuls. La valeur de ce champ est positionn�e par le pilote g�n�rique (partie noyau).

L'exemple de fonction qui suit s'interface directement avec le pilote g�n�rique du noyau. Il d�finit la structure d'en-t�te, envoie la commande par write, lit le r�sultat par read et effectue un nombre (limit�) de contr�les d'erreurs. Les donn�es du tampon SCSI sont disponibles dans le tampon de sortie (sauf si un pointeur nul a �t� fourni, auquel cas elles se trouvent dans le tampon d'entr�e). Nous l'utiliserons dans les exemples qui suivent.

Note : positionnez la valeur de DEVICE � celle qui correspond � votre mat�riel.

#define DEVICE "/dev/sgc"

/* Programme d'exemple utilisant l'interface SCSI g�n�rique */
#include <stdio.h>
#include <unistd.h>
#include <string.h>
#include <fcntl.h>
#include <errno.h>
#include <scsi/sg.h>


#define SCSI_OFF sizeof(struct sg_header)
static  unsigned char cmd[SCSI_OFF + 18];       /* tampon de commande SCSI */
int     fd;                                     /*
                                                 * descripteur de peripherique/
                                                 * fichier SCSI
                                                 */
/* traite une commande SCSI compl�te. Utilise l'interface g�n�rique */
static int handle_SCSI_cmd(unsigned cmd_len,     /* longueur de commande  */
                           unsigned in_size,     /* taille data en entr�e */
                           unsigned char *i_buff,/* tampon d'entr�e       *//
                           unsigned out_size,    /* taille data en sortie */
                           unsigned char *o_buff /* tampon de sortie      */
                           )
{
    int status = 0;
    struct sg_header *sg_hd;

    /* v�rifications de s�curit� */
    if (!cmd_len) return -1;            /* n�cessite que cmd_len != 0 */
    if (!i_buff) return -1;             /* n�cessite que i_buff != NULL */

#ifdef SG_BIG_BUFF
    if (SCSI_OFF + cmd_len + in_size > SG_BIG_BUFF) return -1;
    if (SCSI_OFF + out_size > SG_BIG_BUFF) return -1;
#else
    if (SCSI_OFF + cmd_len + in_size > 4096) return -1;
    if (SCSI_OFF + out_size > 4096) return -1;
#endif

    if (!o_buff) out_size = 0;          /* pas de tampon de sortie, pas de */
                                        /* taille                          */

    /* construction de l'en-t�te g�n�rique de p�riph�rique */
    sg_hd = (struct sg_header *) i_buff;
    sg_hd->reply_len   = SCSI_OFF + out_size;
    sg_hd->twelve_byte = cmd_len == 12;
    sg_hd->result = 0;
#if     0
    sg_hd->pack_len    = SCSI_OFF + cmd_len + in_size; /* non indispensable */
    sg_hd->pack_id;     /* inutilise */
    sg_hd->other_flags; /* inutilise */
#endif

    /* envoi de la commande */
    status = write( fd, i_buff, SCSI_OFF + cmd_len + in_size );
    if ( status < 0 || status != SCSI_OFF + cmd_len + in_size ||
                       sg_hd->result ) {
        /* condition d'erreur */
        fprintf( stderr, "write(generic) resultat = 0x%x cmd = 0x%x\n",
                    sg_hd->result, i_buff[SCSI_OFF] );
        perror("");
        return status;
    }

    if (!o_buff) o_buff = i_buff; /* contr�le du pointeur du tampon */

    /* r�cup�ration du r�sultat */
    status = read( fd, o_buff, SCSI_OFF + out_size);
    if ( status < 0 || status != SCSI_OFF + out_size || sg_hd->result ) {
        /* condition d'erreur */
        fprintf( stderr, "read(generic) statut = 0x%x, resultat = 0x%x, "
                         "cmd = 0x%x\n",
                         status, sg_hd->result, o_buff[SCSI_OFF] );
        fprintf( stderr, "read(generic) tampon SCSI "
                "%x %x %x %x %x %x %x %x %x %x %x %x %x %x %x %x\n",
                sg_hd->sense_buffer[0],         sg_hd->sense_buffer[1],
                sg_hd->sense_buffer[2],         sg_hd->sense_buffer[3],
                sg_hd->sense_buffer[4],         sg_hd->sense_buffer[5],
                sg_hd->sense_buffer[6],         sg_hd->sense_buffer[7],
                sg_hd->sense_buffer[8],         sg_hd->sense_buffer[9],
                sg_hd->sense_buffer[10],        sg_hd->sense_buffer[11],
                sg_hd->sense_buffer[12],        sg_hd->sense_buffer[13],
                sg_hd->sense_buffer[14],        sg_hd->sense_buffer[15]);
        if (status < 0)
            perror("");
    }
    /* A-t-on ce qu'on attendait ? */
    if (status == SCSI_OFF + out_size) status = 0; /* on a tout */

    return status;  /* 0 indique que tout est bon */
}

Bien que cela puisse sembler quelque peu complexe au premier abord, une grande partie du code est d�di�e aux contr�le et d�tection d'erreurs (ce qui est utile m�me une fois que le code fonctionne correctement).

Handle_SCSI_cmd pr�sente une forme g�n�ralis�e pour tous les types de commandes SCSI, qui correspondent � l'une des cat�gories qui suivent :

     Mode de donn�es            |    Exemple de commande
=============================================================
ni entr�e ni sortie de donn�es  |     test d'unite pr�te
pas d'entr�e, sortie de donn�es |      requ�te, lecture
entr�e de donn�es, pas de sortie| selection de mode, �criture
  entr�e et sortie de donn�es   |     d�tection de mode

9. Exemple de commande de requ�te

L'une des commandes SCSI de base est INQUIRY, utilis�e pour identifier les type et constructeur du p�riph�rique. Voici la d�finition issue de la sp�cification SCSI-2 (se reporter au standard SCSI-2 pour les d�tails).

                            Table 44: Commande INQUIRY
+=====-========-========-========-========-========-========-========-========+
|  Bit|   7    |   6    |   5    |   4    |   3    |   2    |   1    |   0    |
|Octet|        |        |        |        |        |        |        |        |
|=====+=======================================================================|
| 0   |                           Code op�ration (12h)                        |
|-----+-----------------------------------------------------------------------|
| 1   |Num�ro d'unit� logique    |                  R�serv�          |  EVPD  |
|-----+-----------------------------------------------------------------------|
| 2   |                           Code page                                   |
|-----+-----------------------------------------------------------------------|
| 3   |                           R�serv�                                     |
|-----+-----------------------------------------------------------------------|
| 4   |                           Taille d'allocation                         |
|-----+-----------------------------------------------------------------------|
| 5   |                           Contr�le                                    |
+=============================================================================+

Les donn�es en sortie ont l'allure suivante :

                   Table 45: Format standard de donn�es INQUIRY
+=====-========-========-========-========-========-========-========-========+
|  Bit|   7    |   6    |   5    |   4    |   3    |   2    |   1    |   0    |
|Octet|        |        |        |        |        |        |        |        |
|=====+==========================+============================================|
| 0   | Qualificateur de p�riph. |           Type de p�riph�rique             |
|-----+-----------------------------------------------------------------------|
| 1   |  RMB   |                  Modificateur de type de p�riph�rique        |
|-----+-----------------------------------------------------------------------|
| 2   |   Version ISO   |       Version ECMA       |  Version approuv�e ANSI  |
|-----+-----------------+-----------------------------------------------------|
| 3   |  AENC  | TrmIOP |     R�serv�     |   Format de donn�es en r�ponse    |
|-----+-----------------------------------------------------------------------|
| 4   |                    Longueur additionnelle (n-4)                       |
|-----+-----------------------------------------------------------------------|
| 5   |                           R�serv�                                     |
|-----+-----------------------------------------------------------------------|
| 6   |                           R�serv�                                     |
|-----+-----------------------------------------------------------------------|
| 7   | RelAdr | WBus32 | WBus16 |  Sync  | Linked |Reserve | CmdQue | SftRe  |
|-----+-----------------------------------------------------------------------|
| 8   | (MSB)                                                                 |
|- - -+---                      Identification de constructeur             ---|
| 15  |                                                                 (LSB) |
|-----+-----------------------------------------------------------------------|
| 16  | (MSB)                                                                 |
|- - -+---                      Identification de produit                  ---|
| 31  |                                                                 (LSB) |
|-----+-----------------------------------------------------------------------|
| 32  | (MSB)                                                                 |
|- - -+---                      Niveau de r�vision du produit              ---|
| 35  |                                                                 (LSB) |
|-----+-----------------------------------------------------------------------|
| 36  |                                                                       |
|- - -+---                      Sp�cifique constructeur                    ---|
| 55  |                                                                       |
|-----+-----------------------------------------------------------------------|
| 56  |                                                                       |
|- - -+---                        R�serv�                                  ---|
| 95  |                                                                       |
|=====+=======================================================================|
|     |                       Param�tres sp�cifiques constructeur             |
|=====+=======================================================================|
| 96  |                                                                       |
|- - -+---                      Sp�cifique constructeur                    ---|
| n   |                                                                       |
+=============================================================================+

L'exemple qui suit utilise la fonction de bas niveau handle_SCSI_cmd pour effectuer la commande SCSI INQUIRY.

Tout d'abord, nous ajoutons le bloc de commande � l'en-t�te g�n�rique, puis appelons handle_SCSI_cmd. Notez que l'argument taille de tampon en sortie de l'appel handle_SCSI_cmd exclut la taille de l'en-t�te g�n�rique. Apr�s l'ex�cution de la commande, le tampon de sortie contient les informations, sauf si une erreur s'est produite.

#define INQUIRY_CMD     0x12
#define INQUIRY_CMDLEN  6
#define INQUIRY_REPLY_LEN 96
#define INQUIRY_VENDOR  8       /* d�calage vers le nom du constructeur */

/* recherche du constructeur et du mod�le */
static unsigned char *Inquiry ( void )
{
  unsigned char Inqbuffer[ SCSI_OFF + INQUIRY_REPLY_LEN ];
  unsigned char cmdblk [ INQUIRY_CMDLEN ] =
      { INQUIRY_CMD,  /* commande                 */
                  0,  /* lun/r�serv�              */
                  0,  /* code de page             */
                  0,  /* r�serv�                  */
  INQUIRY_REPLY_LEN,  /* longueur allocation      */
                  0 };/* r�serv� / drapeau / lien */

  memcpy( cmd + SCSI_OFF, cmdblk, sizeof(cmdblk) );

  /*
   * +------------------+
   * | struct sg_header | <- commande
   * +------------------+
   * | copie de cmdblk  | <- commande + SCSI_OFF
   * +------------------+
   */

  if (handle_SCSI_cmd(sizeof(cmdblk), 0, cmd,
                      sizeof(Inqbuffer) - SCSI_OFF, Inqbuffer )) {
      fprintf( stderr, "La requete a echoue\n" );
      exit(2);
  }
  return (Inqbuffer + SCSI_OFF);
}

L'exemple ci-dessus suit cette structure. La fonction Inquiry recopie son bloc de commande apr�s l'en-t�te g�n�rique (donn� par SCSI_OFF). Les donn�es en entr�e sont absentes de cette commande. handle_SCSI_cmd d�finit la structure d'en-t�te. Nous pouvons maintenant impl�menter la fonction main qui compl�te ce programme d'exemple fonctionnel.

void main( void )
{
  fd = open(DEVICE, O_RDWR);
  if (fd < 0) {
    fprintf( stderr, "Il faut les permissions lecture/ecriture pour "DEVICE".\n" );
    exit(1);
  }

  /* affiche certains champs du r�sultat de Inquiry() */
  printf( "%s\n", Inquiry() + INQUIRY_VENDOR );
}

Tout d'abord, nous ouvrons le p�riph�rique, contr�lons l'absence d'erreur, puis appelons la fonction de haut niveau. Ensuite, nous affichons des r�sultats sous une forme lisible, dont le constructeur, le produit et la version.

Note : il y a plus d'informations dans le r�sultat de "Inquiry" que ce que fournit ce petit programme. Il vous est loisible d'�tendre celui-ci au type de p�riph�rique, version ANSI, etc. Le type de p�riph�rique a une importance particuli�re, puisqu'il d�termine les jeux de commandes obligatoires et facultatives pour celui-ci. Si vous ne souhaitez pas le programmer vous-m�me, Eric Youngdale a r�alis� le programme scsiinfo, qui fournit � peu pr�s toute information disponible pour un p�riph�rique SCSI. Cherchez sur tsx-11.mit.edu dans pub/Linux/ALPHA/scsi (NdT : on trouvera ce programme sur les sites miroirs fran�ais, comme ftp.ibp.fr, � un emplacement similaire).

10. Le "tampon SCSI"

Les commandes qui ne renvoient pas de donn�es peuvent fournir des informations d'�tat � l'aide du tampon SCSI (qui fait partie int�grante de la structure d'en-t�te). Les donn�es d'�tat sont disponibles lorsque la commande pr�c�dente s'est termin�e avec un statut "CHECK CONDITION". Dans ce cas, le noyau rapatrie automatiquement les donn�es d'�tat � l'aide d'une commande "REQUEST SENSE". Sa structure est la suivante :

+=====-========-========-========-========-========-========-========-========+
|  Bit|   7    |   6    |   5    |   4    |   3    |   2    |   1    |   0    |
|Octet|        |        |        |        |        |        |        |        |
|=====+========+==============================================================|
| 0   | Valide |                  Code d'erreur (70h ou 71h)                  |
|-----+-----------------------------------------------------------------------|
| 1   |                           Num�ro de segment                           |
|-----+-----------------------------------------------------------------------|
| 2   |Filemark|  EOM   |  ILI   |R�serv� |         Clef d'�tat               |
|-----+-----------------------------------------------------------------------|
| 3   | (MSB)                                                                 |
|- - -+---                        Information                              ---|
| 6   |                                                                 (LSB) |
|-----+-----------------------------------------------------------------------|
| 7   |                           Longueur additionnelle d'�tat (n-7)         |
|-----+-----------------------------------------------------------------------|
| 8   | (MSB)                                                                 |
|- - -+---                        Information sp�cifique de la commande    ---|
| 11  |                                                                 (LSB) |
|-----+-----------------------------------------------------------------------|
| 12  |                           Code d'�tat additionnel                     |
|-----+-----------------------------------------------------------------------|
| 13  |                           Qualificateur de code d'�tat additionnel    |
|-----+-----------------------------------------------------------------------|
| 14  |                           Code d'unit� de champ rempla�able           |
|-----+-----------------------------------------------------------------------|
| 15  |  SKSV  |                                                              |
|- - -+------------               Sp�cifique clef d'�tat                   ---|
| 17  |                                                                       |
|-----+-----------------------------------------------------------------------|
| 18  |                                                                       |
|- - -+---                        Octets suppl�mentaires d'�tat            ---|
| n   |                                                                       |
+=============================================================================+

Note : les champs les plus utiles sont la clef d'�tat (cf. section Clefs du buffer SCSI), le code d'�tat additionnel et le qualificateur de code d'�tat additionnel (cf. section Codes et qualificateurs du buffer SCSI additionnels). Les deux derniers sont utilis�s en combinaison l'un avec l'autre.

11. Exemple d'utilisation du tampon SCSI

Nous allons utiliser ici la commande "TEST UNIT READY" pour contr�ler si un support est charg� dans notre p�riph�rique. Les d�clarations d'en-t�te et la fonction handle_SCSI_cmd de l'exemple de "Inquiry" seront aussi n�cessaires.

                        Table 73: Commande TEST UNIT READY
+=====-========-========-========-========-========-========-========-========+
|  Bit|   7    |   6    |   5    |   4    |   3    |   2    |   1    |   0    |
|Octet|        |        |        |        |        |        |        |        |
|=====+=======================================================================|
| 0   |                           Code op�ration (00h)                        |
|-----+-----------------------------------------------------------------------|
| 1   |Numero d'unit� logique LUN|                  R�serv�                   |
|-----+-----------------------------------------------------------------------|
| 2   |                           R�serv�                                     |
|-----+-----------------------------------------------------------------------|
| 3   |                           R�serv�                                     |
|-----+-----------------------------------------------------------------------|
| 4   |                           R�serv�                                     |
|-----+-----------------------------------------------------------------------|
| 5   |                           Contr�le                                    |
+=============================================================================+

Voici la fonction qui l'impl�mente :

#define TESTUNITREADY_CMD 0
#define TESTUNITREADY_CMDLEN 6

#define ADD_SENSECODE 12
#define ADD_SC_QUALIFIER 13
#define NO_MEDIA_SC 0x3a
#define NO_MEDIA_SCQ 0x00

int TestForMedium ( void )
{
  /* demande le statut READY */
  static unsigned char cmdblk [TESTUNITREADY_CMDLEN] = {
      TESTUNITREADY_CMD, /* commande */
                      0, /* lun/r�serv� */
                      0, /* r�serv� */
                      0, /* r�serv� */
                      0, /* r�serv� */
                      0};/* contr�le */

  memcpy( cmd + SCSI_OFF, cmdblk, sizeof(cmdblk) );

  /*
   * +------------------+
   * | struct sg_header | <- commande
   * +------------------+
   * | copie de cmdblk  | <- commande + SCSI_OFF
   * +------------------+
   */

  if (handle_SCSI_cmd(sizeof(cmdblk), 0, cmd,
                            0, NULL)) {
      fprintf (stderr, "Unite non prete\n");
      exit(2);
  }

  return
   *(((struct sg_header*)cmd)->sense_buffer +ADD_SENSECODE) !=
                                                        NO_MEDIA_SC ||
   *(((struct sg_header*)cmd)->sense_buffer +ADD_SC_QUALIFIER) !=
                                                        NO_MEDIA_SCQ;
}

Nous pouvons maintenant r�aliser le contr�le � l'aide de la fonction main :

void main( void )
{
  fd = open(DEVICE, O_RDWR);
  if (fd < 0) {
    fprintf( stderr, "Il faut les permissions lecture/ecriture pour "DEVICE".\n"
 );
    exit(1);
  }

  /* on regarde si le support est charge */

  if (!TestForMedium()) {
    printf("le support n'est pas charge\n");
  } else {
    printf("le support est charge\n");
  }
}

Le fichier generic_demo.c en annexe contient les deux exemples.

12. Fonctions ioctl

Deux fonctions ioctl sont disponibles :

13. Valeurs par d�faut du pilote

13.1 Tailles de transfert

Actuellement (au moins jusqu'au noyau version 1.1.68), les tailles d'entr�e et de sortie doivent �tre inf�rieures ou �gales � 4096 octets, sauf si le noyau a �t� compil� avec la constante SG_BIG_BUFF d�finie, auquel cas elles sont limit�es � SG_BIG_BUFF (soit 32768) octets. Les tailles donn�es comprennent l'en-t�te g�n�rique ainsi que le bloc de commande fourni en entr�e. SG_BIG_BUFF peut �tre augment�e sans probl�me jusqu'� (131072 - 512). Pour en b�n�ficier, vous devrez bien �videmment reg�n�rer un nouveau noyau et red�marrer avec.

13.2 Timeout et valeurs de r�essais

La valeur du timeout par d�faut est d'une minute (Timeout = 6 000). Elle peut �tre modifi�e � l'aide d'un appel � ioctl (cf. section Fonctions ioctl). Le nombre de r�essais par d�faut est un.

14. Comment obtenir les sp�cifications SCSI ?

Il existe des normes appel�es SCSI-1, SCSI-2 et SCSI-3. Les normes assurent � peu de choses pr�s la compatibilit� ascendante.

Le standard SCSI-1 est (d'apr�s l'auteur) en grande partie obsol�te, et SCSI-2 est celui qui est le plus largement utilis�. SCSI-3 est tr�s jeune et tr�s cher. Ces jeux de commandes normalis�s d�finissent des commandes obligatoires et facultatives pour les constructeurs de mat�riels SCSI et doivent �tre pr�f�r�es aux extensions sp�cifiques non normalis�es et pour lesquelles l'information est plus difficile � obtenir. Evidemment, il n'y a parfois aucune alternative � ces extensions propri�taires.

Des copies �lectroniques sont disponibles par FTP anonyme depuis :

(J'ai eu mes sp�cifications SCSI dans le CD-ROM Linux d'Yggdrasil, dans le r�pertoires /usr/doc/scsi-2 et /usr/doc/scsi-1).

La FAQ SCSI liste aussi les sources d'information imprim�e suivantes :

Les sp�cifications SCSI - disponible depuis :

      Global Engineering Documents
      15 Inverness Way East
      Englewood Co  80112-5704
      (800) 854-7179
        SCSI-1: X3.131-1986
        SCSI-2: X3.131-199x
        SCSI-3 X3T9.2/91-010R4 Working Draft

(Global Engineering Documentation in Irvine, CA (714)261-1455??)

SCSI-1: Doc \# X3.131-1986 from ANSI, 1430 Broadway, NY, NY 10018

IN-DEPTH EXPLORATION OF SCSI peut �tre trouv� chez
Solution Technology, Attn: SCSI Publications, POB 104, Boulder Creek,
CA 95006, (408)338-4285, FAX (408)338-4374

THE SCSI ENCYLOPEDIA et SCSI BENCH REFERENCE peuvent �tre obtenus chez
ENDL Publishing, 14426 Black Walnut Ct., Saratoga, CA 95090,
(408)867-6642, FAX (408)867-2115

SCSI: UNDERSTANDING THE SMALL COMPUTER SYSTEM INTERFACE est publi� chez
Prentice-Hall, ISBN 0-13-796855-8

15. D'autres sources d'information

15.1 HOWTOs et FAQs

Le SCSI-HOWTO Linux de Drew Eckhardt (NdT : disponible en version fran�aise) traite de tous les contr�leurs SCSI reconnus ainsi que des questions sp�cifiques aux p�riph�riques. De nombreux aides pour le d�pannage sont fournies. Il est disponible sur sunsite.unc.edu dans /pub/Linux/docs/LDP et sur ses sites miroirs.

Les questions g�n�rales concernant le SCSI ont une r�ponse dans la FAQ SCSI du groupe de news comp.periphs.scsi (disponible sur tsx-11 dans /pub/linux/ALPHA/scsi et sur les sites miroirs).

15.2 La liste de messagerie

Il existe une liste de messagerie qui traite des rapports d'anomalies et questions sur le d�veloppement SCSI sous Linux. Pour la rejoindre, envoyez un courrier � majordomo@vger.rutgers.edu avec la ligne subscribe linux-scsi dans le corps du message. Les messages doivent �tre envoy�s � linux-scsi@vger.rutgers.edu. Un texte d'aide peut �tre demand� par envoi de la ligne de message "help" � majordomo@vger.rutgers.edu.

15.3 Exemples de code

sunsite.unc.edu: apps/graphics/hpscanpbm-0.3a.tar.gz

Ce paquetage g�re un scanner HP scanjet � l'aide de l'interface g�n�rique.

tsx-11.mit.edu: BETA/cdrom/private/mkisofs/cdwrite-1.3.tar.gz

Le paquetage cdwrite utilise l'interface g�n�rique pour �crire une image de CD sur un graveur.

sunsite.unc.edu: apps/sound/cds/cdda2wav*.src.tar.gz

Un composant pour mes propres applications, qui copie des pistes audio de CD sous forme de fichiers wav.

16. Autres choses utiles

Des choses qui pourraient devenir pratiques. Je n'ai aucune id�e de la pr�sence de versions plus r�centes ou meilleures ici ou l�. Toute information est la bienvenue.

16.1 Aides � l'�criture de pilotes de p�riph�riques

Ces documents peuvent �tre trouv�s sur le serveur ftp de sunsite.unc.edu et sur ses miroirs.

/pub/Linux/docs/kernel/kernel-hackers-guide

Le guide des stakhanovistes du noyau LDP (NdT : Projet de Documentation Linux). Il est peut-�tre un peu ancien, mais traite les points les plus fondamentaux.

/pub/Linux/docs/kernel/drivers.doc.z

Ce document traite de l'�criture de pilotes caract�res.

/pub/Linux/docs/kernel/tutorial.doc.z

Tutoriel sur l'�criture d'un pilote de p�riph�rique caract�re avec le code.

/pub/Linux/docs/kernel/scsi.paper.tar.gz

Un document Latex d�crivant comment �crire un pilote SCSI.

/pub/Linux/docs/hardware/DEVICES

Une liste des num�ros majeurs et mineurs utilis�s par Linux.

16.2 Utilitaires

tsx-11.mit.edu: ALPHA/scsi/scsiinfo*.tar.gz

Programme d'interrogation d'un p�riph�rique SCSI pour obtenir ses param�tres d'utilisation, listes de d�fauts, etc. Une interface X n�cessitant Tk/Tcl/wish est disponible. Avec cette derni�re, vous pouvez facilement modifier la configuration du lecteur.

tsx-11.mit.edu: ALPHA/kdebug

Une extension � pour le d�verminage du noyau.

17. Autres interfaces d'acc�s au SCSI

Sous Linux, on peut acc�der diff�remment au SCSI via des appels ioctl SCSI_IOCTL_SEND_COMMAND qui n�cessitent des privil�ges root. Les paquetages "scsiinfos" ainsi que "cdda2wav" les utilisent.

D'autres interfaces similaires sont utilis�es dans le monde Unix, mais ne sont pas disponibles pour Linux :

  1. CAM (Common Access Method) d�velopp�e par Future Domain et d'autres constructeurs SCSI. Linux dispose maintenant d'un petit support pour un syst�me CAM SCSI (essentiellement pour bouter depuis un disque dur). CAM supporte m�me le mode "target", qui permet de d�guiser un ordinateur en p�riph�rique SCSI (c.�.d. r�aliser un petit r�seau SCSI).
  2. ASPI (Advanced SCSI Programming Interface) developp�e par Adaptec. C'est le standard de facto pour les machines MS-DOS.
  3. ??? est disponible sur NeXTStep.
  4. DSLIB est disponible sur Silicon Graphics.
  5. SCSI... est disponible sur les machines SUN.
  6. SCO Unix a aussi quelque chose.
  7. HPUX utilise des ioctl. -->

D'autres interfaces applicatives existent aussi chez SCO(TM), NeXT(TM), Silicon Graphics(TM) et SUN(TM).

18. Commentaires finals

L'interface g�n�rique SCSI jette un pont sur le foss� entre les applications utilisateur et les p�riph�riques sp�cifiques. Mais plut�t que de charger de nombreux programmes avec des jeux similaires de fonctions de bas niveau, il serait plus souhaitable de disposer d'une biblioth�que partag�e avec un jeu g�n�ralis� de fonctions de bas niveau pour un usage particulier. Le but principal est de disposer de couches d'interfaces ind�pendantes. Une bonne conception doit s�parer une application en routines de bas niveau et ind�pendantes du mat�riel. Celles-ci peuvent �tre plac�es dans une biblioth�que partag�e et rendues disponibles pour toutes les applications. Ainsi, les interfaces standardis�es doivent �tre suivies autant que possible avant d'en r�aliser de nouvelles.

Vous devriez maintenant en savoir plus que moi sur l'interface g�n�rique SCSI de Linux. Vous pouvez donc commencer � d�velopper de puissantes applications pour le plus grand b�n�fice de la communaut� Linux...

19. Remerciements

Un grand merci � Jeff Tranter pour ses corrections et am�liorations consid�rables de ce texte, ainsi qu'� Carlos Puchol pour ses commentaires utiles. L'aide de Drew Eckhardt et Eric Youngdale sur mes premi�res questions (idiotes) sur l'utilisation de cette interface a �t� appr�ci�e.

20. Annexe

21. Traitement d'erreurs

Les fonctions open, ioctl, write et read peuvent renvoyer des erreurs. Dans ce cas, leur valeur de retour est -1 et la variable globale errno est positionn�e au num�ro d'erreur (n�gatif). Les valeurs de errno sont d�finies dans /usr/include/errno.h. Les valeurs n�gatives possibles sont les suivantes :

Fonction | Erreur       | Description
=========|==============|==================================================
open     |  ENXIO       | p�riph�rique invalide
         |  EACCES      | l'acc�s n'est pas en lecture/�criture (O_RDWR)
         |  EBUSY       | le p�riph�rique est acc�d� en mode non bloquant,
         |              | mais il est occup� actuellement
         |  ERESTARTSYS | erreur interne. Essayez de la rendre reproductible
         |              | et informez-en le canal SCSI (pour les d�tails sur
         |              | le rapport de bogue, se reporter au SCSI-HOWTO de
         |              | Drew Eckhardts).
ioctl    |  ENXIO       | p�riph�rique invalide
read     |  EAGAIN      | le p�riph�rique bloqu�. Essayez plus tard.
         |  ERESTARTSYS | erreur interne. Essayez de la rendre reproductible
         |              | et informez-en le canal SCSI (pour les d�tails sur
         |              | le rapport de bogue, se reporter au SCSI-HOWTO de
         |              | Drew Eckhardts).
write    |  EIO         | taille trop petite (plus petite que cette de l'en-
         |              | t�te g�n�rique). Attention : il n'y a actuellement
         |              | aucun contr�le de d�bordement.
         |  EAGAIN      | le p�riph�rique bloqu�. Essayez plus tard.
         |  ENOMEM      | la m�moire n�cessaire pour cette requ�te ne peut
         |              | �tre allou�e. Essayez plus tard sauf si vous depas-
         |              | sez la taille maximale de transfert (cf. ci-dessus).
select   |              | sans description
close    |              | sans description

Pour la lecture et l'�criture, des valeurs de retour positivent indiquent comme d'habitude la quantit� d'octets transf�r�s. Cette valeur doit correspondre � celle demand�e.

21.1 D�codage de l'�tat d'erreur

En plus, une information d�taill�e est fournie par hd_status du noyau et par sense_buffer du p�riph�rique (cf. section ref id="sec-sensebuff" name="Le tampon SCSI">), les deux utilisant la structure d'en-t�te g�n�rique.

Les diff�rents sens de hd_status peuvent �tre trouv�s dans drivers/scsi/scsi.h. Cet unsigned int est compos� de diff�rentes parties :

  lsb  |    ...    |    ...    | msb
=======|===========|===========|============
status | sense key | host code | driver byte

Les macros de drivers/scsi/scsi.h sont disponibles, mais elles ne peuvent malheureusement pas �tre facilement utilis�es � cause d'interd�pendances tordues entre fichiers d'en-t�te. Il faudrait faire une passe sur ces fichiers pour clarifier les choses.

        Macro          | Description
=======================|=================================================
status_byte(hd_status) | Etat du p�riph�rique. cf. section Codes d'etat
msg_byte(hd_status)    | du p�ripherique. cf. section buffer SCSI
host_byte(hd_status)   | du noyau. cf. section codes h�te
driver_byte(hd_status) | du noyau. cf. section codes interm�diaires

21.2 Codes d'�tat

Les codes d'�tat de p�riph�rique qui suivent (issus de drivers/scsi/scsi.h) sont disponibles :

Valeur | Symbole
=======|=====================
0x00   | GOOD
0x01   | CHECK_CONDITION
0x02   | CONDITION_GOOD
0x04   | BUSY
0x08   | INTERMEDIATE_GOOD
0x0a   | INTERMEDIATE_C_GOOD
0x0c   | RESERVATION_CONFLICT

On constate que ces valeurs symboliques ont subi un d�calage droit. Lorsque l'�tat indique CHECK_CONDITION, les donn�es du buffer SCSI sont valides (contr�lez en particulier le code d'�tat additionnel et le qualificateur de code d'�tat additionnel).

Les valeurs qui suivent concernent les sp�cifications SCSI-2 :

                  Table 27 : Code de l'octet d'�tat
+=================================-==============================+
|      Bits de l'octet d'�tat     |  Etat                        |
|  7   6   5   4   3   2   1   0  |                              |
|---------------------------------+------------------------------|
|  R   R   0   0   0   0   0   R  |  GOOD                        |
|  R   R   0   0   0   0   1   R  |  CHECK CONDITION             |
|  R   R   0   0   0   1   0   R  |  CONDITION MET               |
|  R   R   0   0   1   0   0   R  |  BUSY                        |
|  R   R   0   1   0   0   0   R  |  INTERMEDIATE                |
|  R   R   0   1   0   1   0   R  |  INTERMEDIATE-CONDITION MET  |
|  R   R   0   1   1   0   0   R  |  RESERVATION CONFLICT        |
|  R   R   1   0   0   0   1   R  |  COMMAND TERMINATED          |
|  R   R   1   0   1   0   0   R  |  QUEUE FULL                  |
|                                 |                              |
|       Tous autres codes         |  R�serv�                     |
|----------------------------------------------------------------|
|       R = Bit r�serv�                                          |
+================================================================+

La d�finition des codes de l'octet d'�tat sont donn�es ci-dessous :

GOOD.

Cet �tat indique que la cible a correctement ex�cut� la commande.

CHECK CONDITION.

Cet �tat indique qu'une condition de contention s'est produite (cf. 6.6).

CONDITION MET.

Cet �tat, ou INTERMEDIATE-CONDITION MET est renvoy� lorsque les conditions de l'op�ration demand�e sont satisfaites (cf. commandes SEARCH DATA et PRE-FETCH).

BUSY.

Cet �tat indique que la cible est occup�e. Il peut �tre renvoy� lorsque la cible ne peut accepter de commande depuis un initiateur inacceptable par ailleurs (i.e. conflit d'absence de r�servation). L'action de reprise recommand�e est une nouvelle tentative ult�rieure.

INTERMEDIATE.

Cet �tat, ou INTERMEDIATE-CONDITION MET doit �tre renvoy�e apr�s chaque commande r�ussie d'une s�rie de commandes li�es (sauf pour la derni�re), sauf si celle-ci se termine par un CHECK CONDITION, RESERVATION CONFLICT, ou COMMAND TERMINATED. Si ni INTERMEDIATE ni INTERMEDIATE-CONDITION MET n'est renvoy�, la s�rie de commandes se termine, ainsi que le processus d'entr�es/sorties.

INTERMEDIATE-CONDITION MET.

Cet �tat est la combinaison de CONDITION MET et de INTERMEDIATE.

RESERVATION CONFLICT.

Cet �tat doit �tre renvoy� lorsqu'un initiateur tente d'acc�der � une unit� logique ou � un extension � l'int�rieur d'une unit� logique r�serv�e avec un type de r�servation en conflit pour un autre p�riph�rique SCSI (cf. commandes RESERVE et RESERVE UNIT). L'action de reprise recommand�e est une nouvelle tentative ult�rieure.

COMMAND TERMINATED.

Cet �tat doit �tre renvoy� lorsque la cible termine le processus d'entr�es/sorties apr�s r�ception d'un message TERMINATE I/O PROCESS (cf. 5.6.22). Cet �tat indique aussi qu'une condition de contention s'est produite (cf. 6.6).

QUEUE FULL.

Cet �tat doit �tre impl�ment� si la file d'attente marqu�e (tagged queuing) l'est aussi. Il est renvoy� lors de la r�ception d'un message SIMPLE QUEUE TAG, ORDERED QUEUE TAG, ou HEAD OF QUEUE TAG et que la file de commandes est pleine. Le processus d'entr�e/sortie n'est alors pas plac� dans la file de commandes.

21.3 Clefs du buffer SCSI

Les clefs r�sultantes peuvent �tre rapatri�es � l'aide de la macro msg_byte (cf. section D�codage de l'�tat d'erreur). Les symboles du noyau qui suivent sont pr�d�finis dans drivers/scsi/scsi.h :

Valeur | Symbole
=======|================
0x00   | NO_SENSE
0x01   | RECOVERED_ERROR
0x02   | NOT_READY
0x03   | MEDIUM_ERROR
0x04   | HARDWARE_ERROR
0x05   | ILLEGAL_REQUEST
0x06   | UNIT_ATTENTION
0x07   | DATA_PROTECT
0x08   | BLANK_CHECK
0x0a   | COPY_ABORTED
0x0b   | ABORTED_COMMAND
0x0d   | VOLUME_OVERFLOW
0x0e   | MISCOMPARE

Une liste extraite de la doc SCSI-2 suit (issue de la section 7.2.14.3) :

        Table 69: Description des clefs (0h-7h) du buffer SCSI
+========-====================================================================+
|  Clef  |  Description                                                       |
|--------+--------------------------------------------------------------------|
|   0h   |  NO SENSE.  Indique qu'aucune information sp�cifique n'est         |
|        |  disponible pour l'unit� logique d�sign�e. C'est le cas pour les   |
|        |  commandes r�ussies ou celles dont l'�tat est CHECK CONDITION ou   |
|        |  COMMAND TERMINATED � cause de l'un des bits filemark, EOM ou ILI. |
|--------+--------------------------------------------------------------------|
|   1h   |  RECOVERED ERROR.  Indique que la r�ussite de la derni�re commande |
|        |  fut conditionn�e par une action de r�paration effectu�e par la    |
|        |  cible. Les octets additionnels peuvent fournir des d�tails, ainsi |
|        |  que le champ information. Lorsque plusieurs erreurs r�par�es se   |
|        |  produisent durant une commande, le choix de celle indiqu�e        |
|        |  (premi�re, derni�re, plus s�v�re, etc.) d�pend du p�riph�rique.   |
|--------+--------------------------------------------------------------------|
|   2h   |  NOT READY.  Indique que l'unit� logique est inaccessible. Une     |
|        |  intervention manuelle peut �tre n�cessaire.                       |
|--------+--------------------------------------------------------------------|
|   3h   |  MEDIUM ERROR.  Indique la fin d'une commande sur une erreur non-  |
|        |  r�cup�rable, caus�e probablement par un d�faut du support ou une  |
|        |  erreur de donn�es. Cette clef peut aussi �tre renvoy�e si la      |
|        |  cible ne peut faire la distinction entre un d�faut du support et  |
|        |  un d�faut sp�cifique du mat�riel (clef 4h).                       |
|--------+--------------------------------------------------------------------|
|   4h   |  HARDWARE ERROR.  Indique que la cible a d�tect� une erreur mat�-  |
|        |  rielle irr�cup�rable (d�faut du contr�leur, du p�riph�rique, er-  |
|        |  reur de parit�, etc.) lors de l'ex�cution de la commande ou d'un  |
|        |  auto-test.                                                        |
|--------+--------------------------------------------------------------------|
|   5h   |  ILLEGAL REQUEST.  Indique qu'un param�tre ill�gal a �t� d�tect�   |
|        |  dans le bloc de description de commande ou dans les param�tres    |
|        |  additionnels (pour certaines commandes : FORMAT UNIT, SEARCH DATA,|
|        |  etc.). Si la cible d�tecte un param�tre incorrect, il doit termi- |
|        |  ner celle-ci sans modifier le contenu du support. Si le param�tre |
|        |  incorrect se trouve dans les param�tres additionnels, la cible    |
|        |  peut avoir d�j� modifi� le support. Cette clef est aussi renvoy�e |
|        |  lors de la r�ception d'un message IDENTIFY invalide (5.6.7).      |
|--------+--------------------------------------------------------------------|
|   6h   |  UNIT ATTENTION.  Indique que le support amovible a pu �tre chang� |
|        |  ou que la cible a �t� r�initialis�e. Cf. 6.9 pour d'autres infor- |
|        |  mation sur cette condition.                                       |
|--------+--------------------------------------------------------------------|
|   7h   |  DATA PROTECT.  Indique qu'une commande de lecture ou d'�criture a |
|        |  �t� tent�e sur un bloc prot�g� contre cette op�ration. Celle-ci   |
|        |  n'est pas effectu�e.                                              |
+=============================================================================+

        Table 70: Description des clefs (8h-Fh) du buffer SCSI
+========-====================================================================+
|  Clef  |  Description                                                       |
|--------+--------------------------------------------------------------------|
|   8h   |  BLANK CHECK.  Indique qu'un p�riph�rique � �criture unique ou     |
|        |  s�quentiel a trouv� un support vierge ou une indication de fin de |
|        |  donn�es de formatage lors de la lecture, ou qu'un support non     |
|        |  vierge � �criture seule a �t� trouv� pendant l'�criture.          |
|--------+--------------------------------------------------------------------|
|   9h   |  Vendor Specific.  Cette clef est disponible pour indiquer des     |
|        |  cas particuliers sp�cifiques du constructeur.                     |
|--------+--------------------------------------------------------------------|
|   Ah   |  COPY ABORTED.  Indique qu'une commande COPY, COMPARE ou COPY AND  |
|        |  VERIFY a echou� � cause d'une condition d'erreur sur le p�riph�-  |
|        |  rique source, destination ou les deux (cf. 7.2.3.2 pour plus de   |
|        |  d�tails).                                                         |
|--------+--------------------------------------------------------------------|
|   Bh   |  ABORTED COMMAND.  Indique que la cible a abandonn� la commande.   |
|        |  L'initiateur peut �ventuellement corriger le probl�me par une     |
|        |  nouvelle tentative.                                               |
|--------+--------------------------------------------------------------------|
|   Ch   |  EQUAL.  Indique qu'une commande SEARCH DATA a satisfait une con-  |
|        |  dition d'�galit�.                                                 |
|--------+--------------------------------------------------------------------|
|   Dh   |  VOLUME OVERFLOW.  Indique qu'un p�riph�rique � m�moire-tampon a   |
|        |  atteint la fin de partition et que des donn�es non �crites sur le |
|        |  support peuvent rester dans le tampon. Une (ou plusieurs) commande|
|        |  RECOVER BUFFER DATA peut �tre tent�e pour lire les donn�es non    |
|        |  �crites depuis le tampon.                                         |
|--------+--------------------------------------------------------------------|
|   Eh   |  MISCOMPARE.  Indique que les donn�es source ne correspondent pas  |
|        |  � celles lues sur le support.                                     |
|--------+--------------------------------------------------------------------|
|   Fh   |  RESERVE.                                                          |
+=============================================================================+

21.4 Codes h�te

Les codes h�tes qui suivent sont d�finis au niveau de drivers/scsi/scsi.h. Ils sont positionn�s par le pilote du noyau et doivent �tre utilis�s avec la macro host_byte (cf. section D�codage de l'�tat d'erreur) :

Valeur | Symbole        | Description
=======|================|========================================
0x00   | DID_OK         | Pas d'erreur
0x01   | DID_NO_CONNECT | Connexion impossible avant le timeout
0x02   | DID_BUS_BUSY   | BUS occup� durant la p�riode de timeout
0x03   | DID_TIME_OUT   | Timeout atteint pour une autre raison
0x04   | DID_BAD_TARGET | Mauvaise cible
0x05   | DID_ABORT      | Arr�t effectu� pour une autre raison
0x06   | DID_PARITY     | Erreur de parit�
0x07   | DID_ERROR      | Erreur interne
0x08   | DID_RESET      | R�initialis� par quelqu'un
0x09   | DID_BAD_INTR   | Interruption inattendue re�ue

21.5 Codes du pilote

Le pilote de niveau interm�diaire cat�gorise l'�tat renvoy� par le pilote de bas niveau en fonction du buffer SCSI du p�riph�rique. Il sugg�re certaines actions pouvant �tre tent�es comme un r�essai, un abandon ou un changement de topographie. La routine scsi_done de scsi.c effectue un travail tr�s diff�renci� fond� sur host_byte(), status_byte(), msg_byte() et la suggestion pr�c�dente. Ensuite, il positionne l'octet du pilote afin d'indiquer ce qui a �t� r�alis�. L'octet du pilote est en deux parties : l'�tat du pilote et la suggestion. Chaque moiti� est compos�e des valeurs suivantes (de scsi.h) combin�es par un OR :

Valeur | Symbole        | Description ou �tat du pilote
=======|================|========================================
0x00   | DRIVER_OK      | pas d'erreur
0x01   | DRIVER_BUSY    | inutilis�
0x02   | DRIVER_SOFT    | inutilis�
0x03   | DRIVER_MEDIA   | inutilis�
0x04   | DRIVER_ERROR   | erreur interne du pilote
0x05   | DRIVER_INVALID | termin� (DID_BAD_TARGET ou DID_ABORT)
0x06   | DRIVER_TIMEOUT | termin� avec timeout
0x07   | DRIVER_HARD    | termin� avec une erreur fatale
0x08   | DRIVER_SENSE   | buffer SCSI disponible pour informations

Valeur | Symbole        | Description de la suggestion
=======|================|========================================
0x10   | SUGGEST_RETRY  | r�essayer la requ�te SCSI
0x20   | SUGGEST_ABORT  | abandonner la requ�te
0x30   | SUGGEST_REMAP  | remape le bloc (non encore implement�)
0x40   | SUGGEST_DIE    | laisser le noyau tomber en "panic"
0x80   | SUGGEST_SENSE  | lire le buffer SCSI du p�riph�rique
0xff   | SUGGEST_IS_OK  | rien � faire

22. Codes et qualificateurs du buffer SCSI additionnels

Lorsque l'�tat de la commande SCSI ex�cut�e est CHECK_CONDITION, des donn�es sont disponibles dans le buffer SCSI. Les code et qualificateur additionnels se trouvent dans ce tampon.

Je joins ici deux tables issues des sp�cifications SCSI-2. La premi�re est tri�e alphab�tiquement, la seconde, num�riquement (NdT : la traduction ayant un tantinet boulevers� l'ordre alphab�tique, seule la table tri�e par num�ros a �t� conserv�e. Le lecteur pourra se reporter � la version originale en am�ricain pour la liste alphab�tique).

22.1 ASC et ASCQ dans l'ordre num�rique

La table qui suit fournit une liste de descriptions avec les p�riph�riques auxquels elles s'appliquent.

                       Table 364 : Assignements ASC et ASCQ

+=============================================================================+
|           D - p�riph�rique � acc�s Direct (Disque)                          |
|           .T - p�riph�rique � acc�s s�quenTiel (bande magn�Tique)           |
|           . I - Imprimante                                                  |
|           .  P - Processeur                                                 |
|           .  .W -WORM (CD-ROM inscriptible une fois)                        |
|           .  . R - CD-ROM (lecture seule)                                   |
|           .  .  S - Scanner ou num�riseur                                   |
|           .  .  .O - m�moire Optique                                        |
|           .  .  . M - changeur de M�dia                                     |
|           .  .  .  C - p�riph�rique de Communications                       |
|           .  .  .  .                                                        |
| ASC ASCQ  DTIPWRSOMC  DESCRIPTION                                           |
| --- ----              ----------------------------------------------------- |
|  00  00   DTIPWRSOMC  pas d'information additionnelle                       |
|  00  01    T          marque de fichier d�tect�e                            |
|  00  02    T    S     fin de partition/m�dium d�tect�e                      |
|  00  03    T          marque de jeu d�tect�e                                |
|  00  04    T    S     d�but de partition/m�dium d�tect�                     |
|  00  05    T    S     fin de donn�es d�tect�e                               |
|  00  06   DTIPWRSOMC  fin du processus d'E/S                                |
|  00  11   R           lecture audio en cours                                |
|  00  12   R           lecture audio suspendue                               |
|  00  13   R           lecture audio termin�e avec succ�s                    |
|  00  14   R           lecture audio stopp�e pour cause d'erreur             |
|  00  15   R           pas d'�tat audio en cours � retourner                 |
|  01  00   DW  O       pas de signal d'index/de secteur                      |
|  02  00   D   WR OM   d�placement incomplet                                 |
|  03  00   DTI W SO    �chec d'�criture sur le p�riph�rique                  |
|  03  01    T          pas d'�criture en cours                               |
|  03  02    T          trop d'erreurs d'�criture                             |
|  04  00   DTIPWRSOMC  unit� logique non pr�te, cause inconnue               |
|  04  01   DTIPWRSOMC  unit� logique en pr�paration                          |
|  04  02   DTIPWRSOMC  unit� logique non pr�te, commande d'init n�cessaire   |
|  04  03   DTIPWRSOMC  unit� logique non pr�te, intervention manuelle n�cess.|
|  04  04   DTI    O    unit� logique non pr�te, formatage en cours           |
|  05  00   DTI WRSOMC  l'unit� logique ne r�pond pas � la s�lection          |
|  06  00   D   WR OM   pas de position de r�f�rence trouv�e                  |
|  07  00   DTI WRSOM   s�lection de plusieurs p�riph�riques                  |
|  08  00   DTI WRSOMC  �chec de communication avec l'unit� logique           |
|  08  01   DTI WRSOMC  timeout de communication avec l'unit� logique         |
|  08  02   DTI WRSOMC  erreur de parit� en communication avec l'unit� logique|
|  09  00   DT  WR O    erreur de suivi de piste                              |
|  09  01       WR O    d�faillance du servo de suivi de piste                |
|  09  02       WR O    d�faillance du servo de focalisation                  |
|  09  03       WR O    d�faillance du servo de SPINDLE                       |
+=============================================================================+

Table 364 : (suite)
+=============================================================================+
|           D - p�riph�rique � acc�s Direct (Disque)                          |
|           .T - p�riph�rique � acc�s s�quenTiel (bande magn�Tique)           |
|           . I - Imprimante                                                  |
|           .  P - Processeur                                                 |
|           .  .W -WORM (CD-ROM inscriptible une fois)                        |
|           .  . R - CD-ROM (lecture seule)                                   |
|           .  .  S - Scanner ou num�riseur                                   |
|           .  .  .O - m�moire Optique                                        |
|           .  .  . M - changeur de M�dia                                     |
|           .  .  .  C - p�riph�rique de Communications                       |
|           .  .  .  .                                                        |
| ASC ASCQ  DTIPWRSOMC  DESCRIPTION                                           |
| --- ----              ----------------------------------------------------- |
|  0A  00   DTIPWRSOMC  d�bordement de la trace d'erreur                      |
|  0B  00                                                                     |
|  0C  00    T     S    erreur d'�criture                                     |
|  0C  01   D   W  O    erreud d'�criture corrig�e par auto-r�allocation      |
|  0C  02   D   W  O    erreur d'�criture - auto-r�allocation impossible      |
|  0D  00                                                                     |
|  0E  00                                                                     |
|  0F  00                                                                     |
|  10  00   D   W  O    erreur ID, CRC ou ECC                                 |
|  11  00   DT  WRSO    erreur de lecture irr�cup�rable                       |
|  11  01   DT  W SO    nombre d'essais atteint                               |
|  11  02   DT  W SO    erreur trop longue � corriger                         |
|  11  03   DT  W SO    erreurs de lecture multiples                          |
|  11  04   D   W  O    erreur de lecture - auto-r�allocation impossible      |
|  11  05       WR O    erreur irr�cup�rable L-EC                             |
|  11  06       WR O    erreur irr�cup�rable CIRC                             |
|  11  07       W  O    erreur de resynchronisation de donn�es                |
|  11  08    T          lecture de bloc incompl�te                            |
|  11  09    T          pas de br�che trouv�e                                 |
|  11  0A   DT     O    erreur mal corrig�e                                   |
|  11  0B   D   W  O    erreur de lecture - r�assignement recommand�          |
|  11  0C   D   W  O    erreur de lecture - r�ecriture recommand�e            |
|  12  00   D   W  O    marque d'adresse introuvable pour le champ ID         |
|  13  00   D   W  O    marque d'adresse introuvable pour le champ donn�es    |
|  14  00   DTI WRSO    identit� enregistr�e introuvable                      |
|  14  01   DT  WR O    enregistrement introuvable                            |
|  14  02    T          marque de fichier ou de jeu introuvable               |
|  14  03    T          fin de donn�es introuvable                            |
|  14  04    T          erreur de s�quence de bloc                            |
|  15  00   DTI WRSOM   erreur de positionnement al�atoire                    |
|  15  01   DTI WRSOM   erreur de positionnement m�canique                    |
|  15  02   DT  WR O    erreur de positionnement d�tect�e par la lecture      |
|  16  00   DW     O    erreur de marque de synchronisation de donn�es        |
|  17  00   DT  WRSO    donn�es recup�r�es sans correction d'erreur           |
|  17  01   DT  WRSO    donn�es recup�r�es apr�s plusieurs essais             |
|  17  02   DT  WR O    donn�es recup�r�es avec un d�calage de t�te positif   |
|  17  03   DT  WR O    donn�es recup�r�es avec un d�calage de t�te negatif   |
|  17  04       WR O    donn�es recup�r�es avec plusieurs essais et/ou CIRC   |
|  17  05   D   WR O    donn�es recup�r�es sur l'ID de secteur pr�c�dent      |
|  17  06   D   W  O    donn�es recup�r�es sans ECC - donn�es auto-r�allou�es |
|  17  07   D   W  O    donn�es recup�r�es sans ECC - r�assignement recommand�|
|  17  08   D   W  O    donn�es recup�r�es sans ECC - r�ecriture r�command�e  |
|  18  00   DT  WR O    donn�es recup�r�es avec correction d'erreur           |
|  18  01   D   WR O    donn�es recup�r�es avec correction & plusieurs essais |
|  18  02   D   WR O    donn�es recup�r�es - donn�es auto-r�allou�es          |
|  18  03        R      donn�es recup�r�es avec CIRC                          |
|  18  04        R      donn�es recup�r�es avec LEC                           |
|  18  05   D   WR O    donn�es recup�r�es - r�assignement recommand�         |
|  18  06   D   WR O    donn�es recup�r�es - r�ecriture recommand�e           |
+=============================================================================+

Table 364 : (suite)
+=============================================================================+
|           D - p�riph�rique � acc�s Direct (Disque)                          |
|           .T - p�riph�rique � acc�s s�quenTiel (bande magn�Tique)           |
|           . I - Imprimante                                                  |
|           .  P - Processeur                                                 |
|           .  .W -WORM (CD-ROM inscriptible une fois)                        |
|           .  . R - CD-ROM (lecture seule)                                   |
|           .  .  S - Scanner ou num�riseur                                   |
|           .  .  .O - m�moire Optique                                        |
|           .  .  . M - changeur de M�dia                                     |
|           .  .  .  C - p�riph�rique de Communications                       |
|           .  .  .  .                                                        |
| ASC ASCQ  DTIPWRSOMC  DESCRIPTION                                           |
| --- ----              ----------------------------------------------------- |
|  19  00   D      O    erreur de liste de d�fauts                            |
|  19  01   D      O    liste de d�fauts indisponible                         |
|  19  02   D      O    erreur de liste de d�fauts en liste primaire          |
|  19  03   D      O    erreur de liste de d�fauts en liste secondaire (grown)|
|  1A  00   DTIPWRSOMC  erreur de taille de la liste de d�fauts               |
|  1B  00   DTIPWRSOMC  erreur de transfert de donn�es synchrone              |
|  1C  00   D      O    liste de d�fauts introuvable                          |
|  1C  01   D      O    liste de d�fauts primaire introuvable                 |
|  1C  02   D      O    liste de d�fauts secondaire (grown) introuvable       |
|  1D  00   D   W  O    erreur de comparaison durant la v�rification          |
|  1E  00   D   W  O    ID r�cup�r� avec ECC                                  |
|  1F  00                                                                     |
|  20  00   DTIPWRSOMC  code d'op�ration de commande incorrect                |
|  21  00   DT  WR OM   adresse du bloc logique hors limites                  |
|  21  01           M   adresse d'�l�ment incorrecte                          |
|  22  00   D           fonction illegale (seulement 20 00, 24 00 ou 26 00)   |
|  23  00                                                                     |
|  24  00   DTIPWRSOMC  champ incorrect en CDB                                |
|  25  00   DTIPWRSOMC  unit� logique non support�e                           |
|  26  00   DTIPWRSOMC  champ incorrect en liste de param�tres                |
|  26  01   DTIPWRSOMC  param�tre non support�                                |
|  26  02   DTIPWRSOMC  valeur de param�tre incorrecte                        |
|  26  03   DTIPWRSOMC  param�tres de seuil non support�s                     |
|  27  00   DT  W  O    protection en �criture                                |
|  28  00   DTIPWRSOMC  transition non-pr�t/pr�t (changement de m�dium ?)     |
|  28  01           M   acc�s � un �l�ment import ou export                   |
|  29  00   DTIPWRSOMC  allumage, r�init. ou r�init. du bus a eu lieu         |
|  2A  00   DTI WRSOMC  param�tres chang�s                                    |
|  2A  01   DTI WRSOMC  param�tres de mode chang�s                            |
|  2A  02   DTI WRSOMC  param�tres de trace chang�s                           |
|  2B  00   DTIPWRSO C  copie impossible : d�connexion du host impossible     |
|  2C  00   DTIPWRSOMC  erreur de s�quence de commandes                       |
|  2C  01         S     trop de fen�tres sp�cifi�es                           |
|  2C  02         S     combinaison de fen�tres incorrecte sp�cifi�e          |
|  2D  00    T          erreur d'�criture en �crasement de donn�es            |
|  2E  00                                                                     |
|  2F  00   DTIPWRSOMC  commandes annul�es par un autre initiateur            |
|  30  00   DT  WR OM   m�dium incompatible pr�sent                           |
|  30  01   DT  WR O    m�dium illisible - format inconnu                     |
|  30  02   DT  WR O    m�dium illisible - format incompatible                |
|  30  03   DT          cartouche de nettoyage pr�sente                       |
|  31  00   DT  W  O    format du m�dium endommage                            |
|  31  01   D I    O    �chec de la commande de format                        |
|  32  00   D   W  O    plus d'emplacement de d�faut disponible               |
|  32  01   D   W  O    �chec de mise a jour de la liste de d�fauts           |
|  33  00    T          erreur de longueur de bande                           |
|  34  00                                                                     |
|  35  00                                                                     |
|  36  00     I         manque d'encre, de ruban ou de toner                  |
+=============================================================================+

Table 364 : (suite)
+=============================================================================+
|           D - p�riph�rique � acc�s Direct (Disque)                          |
|           .T - p�riph�rique � acc�s s�quenTiel (bande magn�Tique)           |
|           . I - Imprimante                                                  |
|           .  P - Processeur                                                 |
|           .  .W -WORM (CD-ROM inscriptible une fois)                        |
|           .  . R - CD-ROM (lecture seule)                                   |
|           .  .  S - Scanner ou num�riseur                                   |
|           .  .  .O - m�moire Optique                                        |
|           .  .  . M - changeur de M�dia                                     |
|           .  .  .  C - p�riph�rique de Communications                       |
|           .  .  .  .                                                        |
| ASC ASCQ  DTIPWRSOMC  DESCRIPTION                                           |
| --- ----              ----------------------------------------------------- |
|  37  00   DTI WRSOMC  param�tre arrondi                                     |
|  38  00                                                                     |
|  39  00   DTI WRSOMC  sauvegarde de param�tres non support�e                |
|  3A  00   DTI WRSOM   pas de m�dium                                         |
|  3B  00    TI         erreur de positionnement s�quentiel                   |
|  3B  01    T          erreur de positionnement de la bande au d�but         |
|  3B  02    T          erreur de positionnement de la bande � la fin         |
|  3B  03     I         bande ou feuille-�-feuille non pr�t                   |
|  3B  04     I         erreur de SLEW (NdT : !?)                             |
|  3B  05     I         bourrage papier                                       |
|  3B  06     I         haut de page non d�tect�                              |
|  3B  07     I         bas  de page non d�tect�                              |
|  3B  08    T          erreur de repositionnement                            |
|  3B  09         S     lecture apr�s la fin du m�dium                        |
|  3B  0A         S     lecture avant le debut du m�dium                      |
|  3B  0B         S     position apr�s la fin du m�dium                       |
|  3B  0C         S     position avant le debut du m�dium                     |
|  3B  0D           M   emplacement de destination occup�                     |
|  3B  0E           M   emplacement d'origine vide                            |
|  3C  00                                                                     |
|  3D  00   DTIPWRSOMC  bits incorrects dans le message d'identification      |
|  3E  00   DTIPWRSOMC  auto-configuration de l'unit� non encore r�alis�e     |
|  3F  00   DTIPWRSOMC  les conditions de fonctionnement ont chang�           |
|  3F  01   DTIPWRSOMC  le micro-code a �t� chang�                            |
|  3F  02   DTIPWRSOMC  d�finition de fonctionnement modifi�e                 |
|  3F  03   DTIPWRSOMC  les donn�es de requ�te ont chang�                     |
|  40  00   D           d�faillance RAM (40nn obligatoire)                    |
|  40  NN   DTIPWRSOMC  �chec de diagnostic du composant nn (80h-FFh)         |
|  41  00   D           �chec du chemin de donn�es (40nn obligatoire)         |
|  42  00   D           �chec d'alllumage ou d'auto-test (40nn obligatoire)   |
|  43  00   DTIPWRSOMC  erreur de message                                     |
|  44  00   DTIPWRSOMC  d�faillance de cible interne                          |
|  45  00   DTIPWRSOMC  �chec de s�lection ou de res�lection                  |
|  46  00   DTIPWRSOMC  �chec de la r�initialisation logicielle               |
|  47  00   DTIPWRSOMC  erreur de parit� SCSI                                 |
|  48  00   DTIPWRSOMC  r�ception de message d'erreur d�tect� par initiateur  |
|  49  00   DTIPWRSOMC  erreur message incorrect                              |
|  4A  00   DTIPWRSOMC  erreur de phase de commande                           |
|  4B  00   DTIPWRSOMC  erreur de phase de donn�es                            |
|  4C  00   DTIPWRSOMC  �chec de l'auto-configuration de l'unit� logique      |
|  4D  00                                                                     |
|  4E  00   DTIPWRSOMC  commandes en recouvrement                             |
|  4F  00                                                                     |
|  50  00    T          erreur d'�criture en ajout                            |
|  50  01    T          erreur de positionnement en ajout                     |
|  50  02    T          erreur de positionnement par rapport au timing        |
|  51  00    T     O    erreur d'effacement                                   |
|  52  00    T          d�faut de cartouche                                   |
+=============================================================================+

Table 364 : (suite)
+=============================================================================+
|           D - p�riph�rique � acc�s Direct (Disque)                          |
|           .T - p�riph�rique � acc�s s�quenTiel (bande magn�Tique)           |
|           . I - Imprimante                                                  |
|           .  P - Processeur                                                 |
|           .  .W -WORM (CD-ROM inscriptible une fois)                        |
|           .  . R - CD-ROM (lecture seule)                                   |
|           .  .  S - Scanner ou num�riseur                                   |
|           .  .  .O - m�moire Optique                                        |
|           .  .  . M - changeur de M�dia                                     |
|           .  .  .  C - p�riph�rique de Communications                       |
|           .  .  .  .                                                        |
| ASC ASCQ  DTIPWRSOMC  DESCRIPTION                                           |
| --- ----              ----------------------------------------------------- |
|  53  00   DTI WRSOM   �chec de chargement ou d'�jection du m�dium           |
|  53  01    T          �chec de d�chargement de la bande                     |
|  53  02   DT  WR OM   p�riph�rique prot�g� contre le changement de m�dium   |
|  54  00      P        d�faillance de l'interface host-SCSI                  |
|  55  00      P        d�faut de ressources syst�me                          |
|  56  00                                                                     |
|  57  00        R      impossible de r�cup�rer la table du contenu           |
|  58  00          O    la g�n�ration n'existe pas                            |
|  59  00          O    lecture de bloc mis a jour                            |
|  5A  00   DTIPWRSOM   requ�te op�rateur ou demande de changement d'�tat     |
|  5A  01   DT  WR OM   requ�te op�rateur d'extraction du m�dium              |
|  5A  02   DT  W  O    l'op�rateur a s�lectionn� la protection en �criture   |
|  5A  03   DT  W  O    l'op�rateur a s�lectionn� l'autorisation d'�criture   |
|  5B  00   DTIPWRSOM   exception de trace                                    |
|  5B  01   DTIPWRSOM   condition de seuil remplie                            |
|  5B  02   DTIPWRSOM   compteur de trace au maximum                          |
|  5B  03   DTIPWRSOM   plus de code pour la liste de trace                   |
|  5C  00   D      O    changement d'�tat RPL                                 |
|  5C  01   D      O    SPINDLES synchronis�es                                |
|  5C  02   D      O    SPINDLES non synchronis�es                            |
|  5D  00                                                                     |
|  5E  00                                                                     |
|  5F  00                                                                     |
|  60  00         S     d�faillance de la lampe                               |
|  61  00         S     erreur d'acquisition vid�o                            |
|  61  01         S     impossible de capturer la vid�o                       |
|  61  02         S     hors de la zone focalis�e                             |
|  62  00         S     erreur de positionnement de la t�te de digitalisation |
|  63  00        R      fin de zone utilisateur sur cette piste               |
|  64  00        R      mode ill�gal pour cette piste                         |
|  65  00                                                                     |
|  66  00                                                                     |
|  67  00                                                                     |
|  68  00                                                                     |
|  69  00                                                                     |
|  6A  00                                                                     |
|  6B  00                                                                     |
|  6C  00                                                                     |
|  6D  00                                                                     |
|  6E  00                                                                     |
|  6F  00                                                                     |
+=============================================================================+

Table 364 : (fin)
+=============================================================================+
|           D - p�riph�rique � acc�s Direct (Disque)                          |
|           .T - p�riph�rique � acc�s s�quenTiel (bande magn�Tique)           |
|           . I - Imprimante                                                  |
|           .  P - Processeur                                                 |
|           .  .W -WORM (CD-ROM inscriptible une fois)                        |
|           .  . R - CD-ROM (lecture seule)                                   |
|           .  .  S - Scanner ou num�riseur                                   |
|           .  .  .O - m�moire Optique                                        |
|           .  .  . M - changeur de M�dia                                     |
|           .  .  .  C - p�riph�rique de Communications                       |
|           .  .  .  .                                                        |
| ASC ASCQ  DTIPWRSOMC  DESCRIPTION                                           |
| --- ----              ----------------------------------------------------- |
|  70  00                                                                     |
|  71  00                                                                     |
|  72  00                                                                     |
|  73  00                                                                     |
|  74  00                                                                     |
|  75  00                                                                     |
|  76  00                                                                     |
|  77  00                                                                     |
|  78  00                                                                     |
|  79  00                                                                     |
|  7A  00                                                                     |
|  7B  00                                                                     |
|  7C  00                                                                     |
|  7D  00                                                                     |
|  7E  00                                                                     |
|  7F  00                                                                     |
|                                                                             |
|  80  xxh \                                                                  |
|   jusqu'a >  sp�cifique constructeur                                        |
|  FF  xxh /                                                                  |
|                                                                             |
|  xxh 80 \                                                                   |
|  jusqu'a >  qualification du standard ASC sp�cifique constructeur           |
|  xxh FF /                                                                   |
|              TOUS LES CODES VIDES OU NON MONTRES SONT RESERVES              |
+=============================================================================+

23. R�f�rence rapide des commandes SCSI

La table 365 est une liste ordonn�e num�riquement des codes op�ration des commandes.

                        Table 365 : Codes operations SCSI-2

+=============================================================================+
|           D - p�riph�rique � acc�s Direct               Clef de colonne     |
|           .T - p�riph�rique � acc�s s�quenTiel          N = N�cessaire      |
|           . I - Imprimante                              O = Optionnel       |
|           .  P - Processeur                             C = Constructeur    |
|           .  .W -WORM (CD-ROM inscriptible une fois)    R = R�serv�         |
|           .  . R - CD-ROM (lecture seule)                                   |
|           .  .  S - Scanner ou num�riseur                                   |
|           .  .  .O - m�moire Optique                                        |
|           .  .  . M - changeur de M�dia                                     |
|           .  .  .  C - p�riph�rique de Communications                       |
|           .  .  .  .                                                        |
|        OP DTIPWRSOMC Description                                            |
|----------+----------+-------------------------------------------------------|
|        00 NNNNNNNNNN test d'unit� pr�te                                     |
|        01  N         rembobinage                                            |
|        01 O C OO OO  remise � z�ro de l'unit�                               |
|        02 CCCCCC  C                                                         |
|        03 NNNNNNNNNN requ�te de buffer SCSI                                 |
|        04   O        formatage                                              |
|        04 N      O   formatage de l'unite                                   |
|        05 CNCCCC  C  lecture des limites de bloc                            |
|        06 CCCCCC  C                                                         |
|        07         O  initialisation de l'�tat d'un �l�ment                  |
|        07 OCC O  OC  r�assignation de blocs                                 |
|        08          N lecture de message (06)                                |
|        08 ONC OO OC  lecture (06)                                           |
|        08    O       r�ception                                              |
|        09 CCCCCC  C                                                         |
|        0A   N        impression                                             |
|        0A          N �mission de message (06)                               |
|        0A    N       �mission (06)                                          |
|        0A ON  O  OC  �criture (06)                                          |
|        0B O   OO OC  d�placement (06)                                       |
|        0B   O        SLEW et impression                                     |
|        0C CCCCCC  C                                                         |
|        0D CCCCCC  C                                                         |
|        0E CCCCCC  C                                                         |
|        0F COCCCC  C  lecture invers�e                                       |
|        10   O O      synchronisation du tampon                              |
|        10 CN CCC     �criture de marques de fichiers                        |
|        11 CNCCCC     espace                                                 |
|        12 NNNNNNNNNN requ�te                                                |
|        13 COCCCC     v�rification (06)                                      |
|        14 COOCCC     r�cup�ration des donn�es bufferis�es                   |
|        15 ONO OOOOOO s�lection de mode (06)                                 |
|        16 N   NN NO  r�servation                                            |
|        16  NN   N    r�servation d'unit�                                    |
|        17 N   NN NO  lib�ration                                             |
|        17  NN   N    lib�ration d'unit�                                     |
|        18 OOOOOOOO   copie                                                  |
|        19 CNCCCC     effacement                                             |
|        1A ONO OOOOOO lecture du buffer SCSI (06)                            |
|        1B  O         chargement d�chargement                                |
|        1B       O    digitalisation                                         |
|        1B   O        arr�t d'impression                                     |
|        1B O   OO O   arr�t d�marrage de l'unit�                             |
+=============================================================================+

Table 365 : (suite)
+=============================================================================+
|           D - p�riph�rique � acc�s Direct               Clef de colonne     |
|           .T - p�riph�rique � acc�s s�quenTiel          N = N�cessaire      |
|           . I - Imprimante                              O = Optionnel       |
|           .  P - Processeur                             C = Constructeur    |
|           .  .W -WORM (CD-ROM inscriptible une fois)    R = R�serv�         |
|           .  . R - CD-ROM (lecture seule)                                   |
|           .  .  S - Scanner ou num�riseur                                   |
|           .  .  .O - m�moire Optique                                        |
|           .  .  . M - changeur de M�dia                                     |
|           .  .  .  C - p�riph�rique de Communications                       |
|           .  .  .  .                                                        |
|        OP DTIPWRSOMC Description                                            |
|----------+----------+-------------------------------------------------------|
|        1C OOOOOOOOOO r�ception des r�sultats du diagnostic                  |
|        1D NNNNNNNNNN �mission de diagnostic                                 |
|        1E OO  OO OO  protection contre l'enl�vement du m�dium               |
|        1F                                                                   |
|        20 C   CC C                                                          |
|        21 C   CC C                                                          |
|        22 C   CC C                                                          |
|        23 C   CC C                                                          |
|        24 C   CCN    d�finition de fen�tre                                  |
|        25       O    lecture de fen�tre                                     |
|        25 N   N  N   lecture de capacit�                                    |
|        25      N     lecture de capacit� de cd-rom                          |
|        26 C   CC                                                            |
|        27 C   CC                                                            |
|        28          O lecture de message (10)                                |
|        28 N   NNNN   lecture (10)                                           |
|        29 C   CC O   lecture de g�n�ration                                  |
|        2A          O �mission de message (10)                               |
|        2A       O    �mission (10)                                          |
|        2A N   N  N   �criture (10)                                          |
|        2B  O         localisation                                           |
|        2B         O  positionnement sur �l�ment                             |
|        2B O   OO O   d�placement (10)                                       |
|        2C C      O   effacement (10)                                        |
|        2D C   O  O   lecture de bloc mis � jour                             |
|        2E O   O  O   lecture et v�rification (10)                           |
|        2F O   OO O   v�rification (10)                                      |
|        30 O   OO O   lecture de donn�e haute (10)                           |
|        31       O    position d'objet                                       |
|        31 O   OO O   recherche de donn�e �gale (10)                         |
|        32 O   OO O   recherche de donn�e basse (10)                         |
|        33 O   OO O   d�finition de limites (10)                             |
|        34       O    lecture de l'�tat du tampon de donn�es                 |
|        34 O   OO O   pr�-lecture                                            |
|        34  O         lecture de position                                    |
|        35 O   OO O   synchronisation du cache                               |
|        36 O   OO O   verrouillage/d�verrouillage du cache                   |
|        37 O      O   lecture de donn�es d�fectueuses (10)                   |
|        38     O  O   digitalisation du m�dium                               |
|        39 OOOOOOOO   comparaison                                            |
|        3A OOOOOOOO   copie et v�rification                                  |
|        3B OOOOOOOOOO �criture de tampon                                     |
|        3C OOOOOOOOOO lecture de tampon                                      |
|        3D     O  O   mise � jour de bloc                                    |
|        3E O   OO O   lecture longue                                         |
|        3F O   O  O   �criture longue                                        |
+=============================================================================+

Table 365 : (suite)
+=============================================================================+
|           D - p�riph�rique � acc�s Direct               Clef de colonne     |
|           .T - p�riph�rique � acc�s s�quenTiel          N = N�cessaire      |
|           . I - Imprimante                              O = Optionnel       |
|           .  P - Processeur                             C = Constructeur    |
|           .  .W -WORM (CD-ROM inscriptible une fois)    R = R�serv�         |
|           .  . R - CD-ROM (lecture seule)                                   |
|           .  .  S - Scanner ou num�riseur                                   |
|           .  .  .O - m�moire Optique                                        |
|           .  .  . M - changeur de M�dia                                     |
|           .  .  .  C - p�riph�rique de Communications                       |
|           .  .  .  .                                                        |
|        OP DTIPWRSOMC Description                                            |
|----------+----------+-------------------------------------------------------|
|        40 OOOOOOOOOO changement de d�finition                               |
|        41 O          �criture identique                                     |
|        42      O     lecture de sous-canal                                  |
|        43      O     lecture du TOC                                         |
|        44      O     lecture d'en-t�te                                      |
|        45      O     lecture audio (10)                                     |
|        46                                                                   |
|        47      O     lecture audio MSF                                      |
|        48      O     lecture d'index de piste audio                         |
|        49      O     lecture de piste relative (10)                         |
|        4A                                                                   |
|        4B      O     reprise de pause                                       |
|        4C OOOOOOOOOO trace de s�lection                                     |
|        4D OOOOOOOOOO trace du buffer SCSI                                   |
|        4E                                                                   |
|        4F                                                                   |
|        50                                                                   |
|        51                                                                   |
|        52                                                                   |
|        53                                                                   |
|        54                                                                   |
|        55 OOO OOOOOO mode de s�lection (10)                                 |
|        56                                                                   |
|        57                                                                   |
|        58                                                                   |
|        59                                                                   |
|        5A OOO OOOOOO mode du buffer SCSI (10)                               |
|        5B                                                                   |
|        5C                                                                   |
|        5D                                                                   |
|        5E                                                                   |
|        5F                                                                   |
+=============================================================================+

Table 365 : (fin)
+=============================================================================+
|           D - p�riph�rique � acc�s Direct               Clef de colonne     |
|           .T - p�riph�rique � acc�s s�quenTiel          N = N�cessaire      |
|           . I - Imprimante                              O = Optionnel       |
|           .  P - Processeur                             C = Constructeur    |
|           .  .W -WORM (CD-ROM inscriptible une fois)    R = R�serv�         |
|           .  . R - CD-ROM (lecture seule)                                   |
|           .  .  S - Scanner ou num�riseur                                   |
|           .  .  .O - m�moire Optique                                        |
|           .  .  . M - changeur de M�dia                                     |
|           .  .  .  C - p�riph�rique de Communications                       |
|           .  .  .  .                                                        |
|        OP DTLPWRSOMC Description                                            |
|----------+----------+-------------------------------------------------------|
|        A0                                                                   |
|        A1                                                                   |
|        A2                                                                   |
|        A3                                                                   |
|        A4                                                                   |
|        A5         N  d�placement de m�dium                                  |
|        A5      O     lecture audio (12)                                     |
|        A6         O  changement de m�dium                                   |
|        A7                                                                   |
|        A8          O lecture de message (12)                                |
|        A8     OO O   lecture (12)                                           |
|        A9      O     lecture de piste relative (12)                         |
|        AA          O �mission de message (12)                               |
|        AA     O  O   �criture (12)                                          |
|        AB                                                                   |
|        AC        O   effacement (12)                                        |
|        AD                                                                   |
|        AE     O  O   �criture et v�rification (12)                          |
|        AF     OO O   v�rification (12)                                      |
|        B0     OO O   recherche de donn�e haute (12)                         |
|        B1     OO O   recherche de donn�e egale (12)                         |
|        B2     OO O   recherche de donn�e basse (12)                         |
|        B3     OO O   d�finition des limites (12)                            |
|        B4                                                                   |
|        B5                                                                   |
|        B5         O  demande d'adresse d'�l�ment volume                     |
|        B6                                                                   |
|        B6         O  �mission de TAG de volume                              |
|        B7        O   lecture des donn�es de d�fauts (12)                    |
|        B8                                                                   |
|        B8         O  lecture de l'�tat d'�l�ment                            |
|        B9                                                                   |
|        BA                                                                   |
|        BB                                                                   |
|        BC                                                                   |
|        BD                                                                   |
|        BE                                                                   |
|        BF                                                                   |
+=============================================================================+

24. Programmes d'exemple

Voici le programme exemple en C qui demande le constructeur et le mod�le et indique si un medium est charg� dans le p�riph�rique.

#define DEVICE "/dev/sgc"
/* Programme de demonstration de l'interface SCSI generique */
#include <stdio.h>
#include <unistd.h>
#include <string.h>
#include <fcntl.h>
#include <errno.h>
#include <scsi/sg.h>

#define SCSI_OFF sizeof(struct sg_header)
static unsigned char cmd[SCSI_OFF + 18];        /* tampon de commandes SCSI */
int     fd;                          /* descripteur de periph./fichier SCSI */

/* traite une commande SCSI complete. Utilise l'interface SCSI generique */

static int handle_scsi_cmd(unsigned cmd_len,         /* longueur */
                           unsigned in_size,         /* taille data IN */
                           unsigned char *i_buff,    /* tampon IN */
                           unsigned out_size,        /* taille data OUT */
                           unsigned char *o_buff     /* tampon OUT */
                           )
{
    int status = 0;
    struct sg_header *sg_hd;

    /* quelques controles de routine */
    if (!cmd_len) return -1;            /* cmd_len doit etre != 0 */
    if (!i_buff) return -1;             /* tampon IN doit etre != NULL */
#ifdef SG_BIG_BUFF
    if (SCSI_OFF + cmd_len + in_size > SG_BIG_BUFF) return -1;
    if (SCSI_OFF + out_size > SG_BIG_BUFF) return -1;
#else
    if (SCSI_OFF + cmd_len + in_size > 4096) return -1;
    if (SCSI_OFF + out_size > 4096) return -1;
#endif

    if (!o_buff) out_size = 0;

    /* construction de l'en-tete du pilote generique */
    sg_hd = (struct sg_header *) i_buff;
    sg_hd->reply_len   = SCSI_OFF + out_size;
    sg_hd->twelve_byte = cmd_len == 12;
    sg_hd->result = 0;
#if     0
    sg_hd->pack_len    = SCSI_OFF + cmd_len + in_size; /* pas indispensable */
    sg_hd->pack_id;     /* inutilise */
    sg_hd->other_flags; /* inutilise */
#endif

    /* envoi de la commande */
    status = write( fd, i_buff, SCSI_OFF + cmd_len + in_size );
    if ( status < 0 || status != SCSI_OFF + cmd_len + in_size ||
                       sg_hd->result ) {
        /* une erreur s'est produite */
        fprintf( stderr, "ecriture (generique) resultat = 0x%x cmd = 0x%x\n",
                    sg_hd->result, i_buff[SCSI_OFF] );
        perror("");
        return status;
    }

    if (!o_buff) o_buff = i_buff;       /* controle du pointeur du tampon */

    /* recuperation du resultat */
    status = read( fd, o_buff, SCSI_OFF + out_size);
    if ( status < 0 || status != SCSI_OFF + out_size || sg_hd->result ) {
        /* une erreur s'est produite */
        fprintf( stderr, "lecture (generique) resultat = 0x%x cmd = 0x%x\n",
                sg_hd->result, o_buff[SCSI_OFF] );
        fprintf( stderr, "read(generic) sense "
                "%x %x %x %x %x %x %x %x %x %x %x %x %x %x %x %x\n",
                sg_hd->sense_buffer[0],         sg_hd->sense_buffer[1],
                sg_hd->sense_buffer[2],         sg_hd->sense_buffer[3],
                sg_hd->sense_buffer[4],         sg_hd->sense_buffer[5],
                sg_hd->sense_buffer[6],         sg_hd->sense_buffer[7],
                sg_hd->sense_buffer[8],         sg_hd->sense_buffer[9],
                sg_hd->sense_buffer[10],        sg_hd->sense_buffer[11],
                sg_hd->sense_buffer[12],        sg_hd->sense_buffer[13],
                sg_hd->sense_buffer[14],        sg_hd->sense_buffer[15]);
        if (status < 0)
            perror("");
    }
    /* Voyons si nous avons ce que nous attendions */
    if (status == SCSI_OFF + out_size) status = 0; /* on a tout */

    return status;  /* 0 indique que tout est OK */
}

#define INQUIRY_CMD     0x12
#define INQUIRY_CMDLEN  6
#define INQUIRY_REPLY_LEN 96
#define INQUIRY_VENDOR  8    /* Decalage sur le constructeur dans la reponse */

/* On demande le constructeur et le modele */
static unsigned char *Inquiry ( void )
{
  unsigned char Inqbuffer[ SCSI_OFF + INQUIRY_REPLY_LEN ];
  unsigned char cmdblk [ INQUIRY_CMDLEN ] =
      { INQUIRY_CMD,  /* commande */
                  0,  /* lun/reserve */
                  0,  /* code page */
                  0,  /* reserve */
  INQUIRY_REPLY_LEN,  /* longueur d'allocation */
                  0 };/* reserve/drapeau/lien */

  memcpy( cmd + SCSI_OFF, cmdblk, sizeof(cmdblk) );

  /*
   * +------------------+
   * | struct sg_header | <- cmd
   * +------------------+
   * | copie de cmdblk  | <- cmd + SCSI_OFF
   * +------------------+
   */

  if (handle_scsi_cmd(sizeof(cmdblk), 0, cmd,
                      sizeof(Inqbuffer) - SCSI_OFF, Inqbuffer )) {
      fprintf( stderr, "Echec de la demande\n" );
      exit(2);
  }
  return (Inqbuffer + SCSI_OFF);
}

#define TESTUNITREADY_CMD 0
#define TESTUNITREADY_CMDLEN 6

#define ADD_SENSECODE 12
#define ADD_SC_QUALIFIER 13
#define NO_MEDIA_SC 0x3a
#define NO_MEDIA_SCQ 0x00
int TestForMedium ( void )
{
  /* demande de l'etat READY */
  static unsigned char cmdblk [TESTUNITREADY_CMDLEN] = {
      TESTUNITREADY_CMD, /* commande */
                      0, /* lun/reserve */
                      0, /* reserve */
                      0, /* reserve */
                      0, /* reserve */
                      0};/* reserve */

  memcpy( cmd + SCSI_OFF, cmdblk, sizeof(cmdblk) );

  /*
   * +------------------+
   * | struct sg_header | <- cmd
   * +------------------+
   * | copie de cmdblk  | <- cmd + SCSI_OFF
   * +------------------+
   */

  if (handle_scsi_cmd(sizeof(cmdblk), 0, cmd,
                            0, NULL)) {
      fprintf (stderr, "Echec du test d'unite prete\n");
      exit(2);
  }

  return
   *(((struct sg_header*)cmd)->sense_buffer +ADD_SENSECODE) !=
                                                        NO_MEDIA_SC ||
   *(((struct sg_header*)cmd)->sense_buffer +ADD_SC_QUALIFIER) !=
                                                        NO_MEDIA_SCQ;
}

void main( void )
{
  fd = open(DEVICE, O_RDWR);
  if (fd < 0) {
    fprintf( stderr, "Il faut les droits lecture/ecriture sur "DEVICE".\n" );
    exit(1);
  }

  /* on ecrit quelques champs du resultat de la requete */
  printf( "%s\n", Inquiry() + INQUIRY_VENDOR );

  /* on regarde si le medium est charge */
  if (!TestForMedium()) {
    printf("pas de medium charge\n");
  } else {
    printf("un medium est present\n");
  }
}