SPU_RUN(2)

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 'stop 0x1234' 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.