SPU_RUN

Section : Manuel du programmeur Linux (2)
Mise à jour de la version anglaise : 25 novembre 2007
Index Menu principal

NOM

spu_run - Exécuter un contexte SPU

SYNOPSIS

#include <sys/spu.h>

int spu_run(int fd, unsigned int *npc, unsigned int *event);

DESCRIPTION

L'appel système spu_run() est utilisé sur les machines PowerPC à base de processeur « Cell Broadband Engine » afin d'accéder aux unités synergiques SPU (Synergistic Processor Units). L'argument fd est un descripteur de fichier renvoyé par spu_create(2) qui fait référence à un contexte SPU spécifique. Lorsque le contexte est transmis à une SPU physique, il démarre son exécution au pointeur d'instruction passé dans npc.

L'exécution du code SPU se fait de manière synchrone, ce qui signifie que spu_run() bloque tant que la SPU est en cours d'exécution. S'il est nécessaire d'exécuter du code SPU en parallèle d'autres codes soit sur le processeur principal, soit sur d'autres SPU, il faut d'abord créer un nouveau thread (par exemple, avec pthread_create(3)).

Lorsque spu_run() revient, la valeur actuelle du compteur programme SPU est écrite dans npc, ainsi, les appels successifs à spu_run() peuvent utiliser le même pointeur npc.

L'argument event fournit un tampon pour un code d'état étendu. Si le contexte SPU a été créé avec l'attribut SPU_CREATE_EVENTS_ENABLED, ce tampon sera rempli par le noyau Linux avant que spu_run() revienne.

Le code d'état peut être l'une (ou plus) des constantes suivantes :

SPE_EVENT_DMA_ALIGNMENT: Une erreur d'alignement DMA s'est produite.
SPE_EVENT_INVALID_DMA: Une commande MFC DMA invalide a été tentée.
SPE_EVENT_SPE_DATA_STORAGE: Une erreur de stockage DMA s'est produite.
SPE_EVENT_SPE_ERROR: Une instruction illégale a été exécutée.

NULL est une valeur valide pour l'argument event. Dans ce cas, les événements ne seront pas signifiés au processus appelant.

VALEUR RENVOYÉE

S'il réussit, spu_run() renvoie la valeur du registre spu_status. S'il échoue, il renvoie -1 et errno contient le code de l'erreur.

La valeur du registre spu_status est un masque de bits de codes d'état et éventuellement un code sur 14 bits renvoyé par l'instruction stop-and-signal de la SPU. Les masques de bits des codes d'états sont :

0x02: La SPU a été arrêtée par l'instruction stop-and-signal.
0x04: La SPU a été arrêté par l'instruction halt.
0x08: La SPU est en attente d'un canal.
0x10: La SPU est en mode simple pas (single-step).
0x20: La SPU a essayé d'exécuter une instruction invalide.
0x40: La SPU a essayé d'accéder à un canal invalide.
0x3fff0000: Les bits masqués avec cette valeur contiennent le code renvoyé par une instruction stop-and-signal. Ces bits ne sont valides que si le bit 0x02 est positionné.

Si spu_run() n'a pas renvoyé d'erreur, au moins un des 8 bits de poids faible est toujours positionné.

ERREURS

EBADF: fd n'est pas un descripteur de fichier valide.
EFAULT: npc n'est pas un pointeur valide ou event n'est ni NULL et ni un pointeur valide.
EINTR: Un signal est apparu alors que spu_run() était en cours d'exécution ; voir signal(7). Si nécessaire, la valeur npc a été mise à jour avec la nouvelle valeur du compteur programme.
EINVAL: fd n'est pas un descripteur de fichier valide renvoyé par spu_create(2).
ENOMEM: Il n'y a pas suffisamment de mémoire disponible pour gérer une faute de page résultant d'un accès direct à la mémoire d'un MFC (« Memory Flow Controller »).
ENOSYS: La fonctionnalité n'est pas fournie par le système, soit parce que le matériel ne fournit pas de SPU, soit parce que le module spufs n'est pas chargé.

VERSIONS

L'appel système spu_run() a été indroduit dans la version 2.6.16 du noyau Linux.

CONFORMITÉ

Cet appel système est spécifique à Linux et n'est implémenté que sur l'architecture PowerPC. Les programmes qui utilisent cet appel système ne sont pas portables.

NOTES

La glibc ne fournit pas d'enveloppe pour cet appel système ; utilisez syscall(2) pour l'appeler. Veuillez noter toutefois que spu_run() est conçu pour être utilisé par des bibliothèques qui implémentent une interface plus abstraite pour les SPU, pas pour être utilisé directement par des applications normales. Voir http://www.bsc.es/projects/deepcomputing/linuxoncell/ pour les bibliothèques recommandées.

EXEMPLE

Voici l'exemple de l'exécution d'un programme simple, à une seule instruction SPU, utilisant l'appel système spu_run().

#include <stdlib.h>
#include <stdint.h>
#include <unistd.h>
#include <stdio.h>
#include <sys/types.h>
#include <fcntl.h>

#define handle_error(msg) \
    do { perror(msg); exit(EXIT_FAILURE); } while (0)

int main(void)
{
    int context, fd, spu_status;
    uint32_t instruction, npc;

    context = spu_create("/spu/example-context", 0, 0755);
    if (context == -1)
        handle_error("spu_create");

    /* write a aqstop 0x1234aq instruction to the SPU's
     * local store memory
     */
    instruction = 0x00001234;

    fd = open("/spu/example-context/mem", O_RDWR);
    if (fd == -1)
        handle_error("open");
    write(fd, &instruction, sizeof(instruction));

    /* set npc to the starting instruction address of the
     * SPU program. Since we wrote the instruction at the
     * start of the mem file, the entry point will be 0x0
     */
    npc = 0;

    spu_status = spu_run(context, &npc, NULL);
    if (spu_status == -1)
        handle_error("open");

    /* we should see a status code of 0x1234002:
     *   0x00000002 (spu was stopped due to stop-and-signal)
     * | 0x12340000 (the stop-and-signal code)
     */
    printf("SPU Status: 0x%08x\n", spu_status);

    exit(EXIT_SUCCESS);
}

VOIR AUSSI

close(2), spu_create(2), capabilities(7), spufs(7)

TRADUCTION

Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> le 18 décembre 2007 et révisée le 17 juillet 2008.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 2 spu_run ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.

Dernière mise à jour : 17 juillet 2008