Communiquer avec les boîtes de messages

Le module mail permet d'échanger des données entre plusieurs tâches. Cette page détaille le fonctionnement et l'utilisation des fonctions de ce module.

1. Synthèse des fonctions

Les fonctions de ce module sont déclarées dans le fichier mk_mail.h :

2. Fonctionnement

Une boîte de messages est construite à partir d'un buffer fourni par l'application. Ce buffer est découpé en plusieurs blocs de taille identique. Chaque bloc constitue un message. La figure ci-dessous montre l'état initial d'une boîte de messages constituée de 4 messages :

Pour chaque message de la boîte, le noyau alloue un petit espace mémoire supplémentaire (item) qui contient les métadonnées suivantes :

• ✔L'adresse du message dans le buffer.
• ✔L'adresse de la tâche qui a posté le message.
• ✔L'adresse du prochain item de la liste.

Lors de son initialisation, l'ensemble des items de la boîte est chaîné et positionné dans la liste des items non utilisés (unusedList). En plus de cette liste, chaque boîte possède deux pointeurs, le poster et le pender qui pointent respectivement sur le dernier message écrit dans la boîte et sur le premier message à lire dans celle-ci.

Les tâches interagissent avec les boîtes de messages de 2 manières. Lors d'un post, la tâche productrice transmet un message au noyau qui le copie dans un emplacement libre de la boîte.

Lors d'un pend, la tâche consommatrice demande au noyau de copier un message de la boîte dans son buffer de destination.

Les figures ci-dessous montrent l'état d'une boîte de messages après trois posts successifs :

Le pender se situe toujours en tête de liste alors que le poster se situe toujours en queue de liste. Lors de chaque post, l'élément au début de unusedList est déplacé dans la liste des items utilisés. Si aucun emplacement n'est disponible dans la boîte, la tâche productrice peut décider de se bloquer en attendant qu'un emplacement se libère.

Les figures ci-dessous montrent l'évolution de la boîte de messages après plusieurs pends successifs.

Les messages sont lus dans l'ordre où ils sont postés (algorithme FIFO). Lors de chaque pend, le message à lire est retiré de la liste des items utilisés pour être déplacé en tête de unusedList. Dans la situation où plus aucun message n'est disponible dans la boîte, la tâche consommatrice peut se bloquer en attendant qu'un message soit posté.

Les figures ci-dessous montrent l'état d'une boîte de messages dans le cas particulier où elle est pleine ou vide :

3. Utilisation

La création d'une boîte s'effectue à partir des fonctions mk_pool_initArea et mk_mail_create. L'exemple ci-dessous crée une boîte de 4 messages :

/* On définit une structure pour l'exemple */
/* Sa taille est de 2 mots */
typedef struct T_message T_message;
struct T_message
{
   uint32_t id;
   uint32_t value;
};

/* On définit la taille du buffer de la boîte */
/* On souhaite pouvoir allouer 4 structures T_message */
#define K_BUF_SIZE ( 4 * ( sizeof ( T_message ) >> 2 ) )

/* Déclaration du buffer de la boîte */
/* Il peut contenir 4 messages de type T_message */
K_MK_PRIVILEGED_BSS_MEMORY uint32_t g_mailBuf [ K_BUF_SIZE ];

/* Pointeur de la boîte */
K_MK_PRIVILEGED_BSS_MEMORY T_mkMail* g_mail;

/* Une tâche privilégiée */
void mk_task_privileged ( T_mkAddr p_param )
{
   /* Déclaration de la variable de retour */
   T_mkCode l_result = K_MK_OK;

   /* Déclaration d'une structure contenant les caractéristiques du buffer */
   T_mkPoolArea l_area = { };

   /* Initialisation du buffer de la boîte */  
   /* La taille est exprimée en mots 32 bits */  
   l_result = mk_pool_initArea ( &l_area, g_mailBuf, K_BUF_SIZE );

   /* Création de la boîte */
   /* Celle-ci est protégée et ne peut pas être manipulée */
   /* par tâches non privilégiées */
   l_result |= mk_mail_create ( &g_mail, K_MK_AREA_PROTECTED, &l_area,
      sizeof ( T_message ) >> 2, /* Taille des messages */
      4 ); /* Nombre de messages */

   /* ... */
   for ( ;; ) ;
}

Après sa création, un message est posté avec mk_mail_post et lu avec mk_mail_pend. Le paramètre p_mkTick définit le comportement de la tâche lorsque l'opération ne peut pas aboutir immédiatement :

/* Tâche productrice */
void mk_producer ( T_mkAddr p_param )
{
   T_mkCode l_result;
   T_message l_message = { 1, 100 };

   while ( 1 )
   {
      /* La tâche attend au maximum 10 ticks un emplacement libre */
      /* Elle reste dans l'état READY suite à l'envoi du message */
      l_result = mk_mail_post ( g_mail, &l_message, K_MK_STATE_READY, 10 );

      if ( l_result == K_MK_OK ) {
         /* Le message a été posté */
      }
      else if ( l_result == K_MK_ERROR_TIMEOUT ) {
         /* Le message n'a pas été posté */
         /* Boîte pleine pendant 10 ticks */
      }
      else {
         /* Gestion des erreurs ...  */
         /* K_MK_ERROR_PARAM, K_MK_ERROR_ISR, K_MK_ERROR_RIGHT */
      }
    }
}

/* Tâche consommatrice */
void mk_consumer ( T_mkAddr p_param )
{
   T_mkCode l_result;
   T_message l_message;
   T_mkTask* l_sender = K_MK_NULL;

   while ( 1 )
   {
      /* Attente infinie d'un message */
      /* l_sender reçoit l'adresse de la tâche qui a posté (optionnel) */
      l_result = mk_mail_pend ( &l_sender, g_mail, &l_message, 
         K_MK_TASK_WAIT_FOREVER );

      /* Si la fonction retourne K_MK_OK, un message a été récupéré */
      if ( l_result == K_MK_OK ) {
         /* Traitement du message ... */
      }
      else { 
         /* Gestion des erreurs ...  */
         /* K_MK_ERROR_PARAM, K_MK_ERROR_ISR, K_MK_ERROR_RIGHT */
      }
   }
}

Le paramètre p_mkState de mk_mail_post indique l'état que doit prendre la tâche appelante une fois le message posté. La constante K_MK_STATE_READY maintient la tâche dans l'état prêt alors que la constante K_MK_STATE_SUSPENDED suspend la tâche après l'écriture du message. La tâche devra alors être redémarrée explicitement par une autre tâche avec la fonction mk_task_resume.

/* Tâche productrice */
void mk_producer ( T_mkAddr p_param )
{
   /* ... */
    
   /* La tâche transfère son message puis se suspend */
   l_result = mk_mail_post ( g_mail, &l_message, 
      K_MK_STATE_SUSPENDED, K_MK_TASK_WAIT_FOREVER );

   /* ... */
}

/* Tâche consommatrice */
void mk_consumer ( T_mkAddr p_param )
{
   /* ... */

   /* On récupère le message et l'adresse de la tâche qui l'a posté */
   l_result = mk_mail_pend ( &l_sender, g_mail, &l_message, 
      K_MK_TASK_WAIT_FOREVER );

   /* ... */
    
   /* Si le message n'a pas été envoyé depuis un vecteur d'interruption */
   if ( l_sender != K_MK_NULL ) {
      /* Le traitement est terminé, on réveille le producteur */
      l_result |= mk_task_resume ( l_sender );
   }   

   /* ... */
}

La copie d'un message dans la boîte peut être coûteuse en termes de mémoire et de rapidité. Dans cette situation, il est préférable de poster une référence plutôt que la donnée elle-même. L'exemple ci-dessous montre un transfert par référence en utilisant une pool mémoire :

/* On définit la taille du buffer de la pool */
/* On souhaite pouvoir allouer 4 structures T_message */
#define K_POOL_SIZE ( 4 * ( sizeof ( T_message ) >> 2 ) )

/* Déclaration du buffer de la pool */
K_MK_PRIVILEGED_BSS_MEMORY uint32_t g_poolBuf [ K_POOL_SIZE ];

/* Déclaration d'un pointeur de pool */
K_MK_PRIVILEGED_BSS_MEMORY T_mkPool* g_pool;

/* Tâche productrice */
void mk_producer ( T_mkAddr p_param )
{
   T_mkCode l_result = K_MK_OK;
   T_message* l_block = K_MK_NULL;
   T_mkPoolArea l_mailArea, l_poolArea;
   uint32_t l_counter = 0;

   /* Initialisation du buffer de la boîte */  
   l_result = mk_pool_initArea ( &l_mailArea, g_mailBuf, 4 );

   /* Initialisation du buffer de la pool */  
   l_result |= mk_pool_initArea ( &l_poolArea, g_poolBuf, K_POOL_SIZE ); 

   /* Création de la boîte (4 messages de 1 mot) */
   /* La taille de la boîte doit faire la taille d'un pointeur */
   l_result |= mk_mail_create ( &g_mail, K_MK_AREA_PROTECTED, 
      &l_mailArea, 1, 4 ); 

   /* Création de la pool (4 structures T_message) */
   l_result |= mk_pool_create ( &l_poolArea, &g_pool, 
      K_MK_AREA_PROTECTED, sizeof ( T_message ) >> 2, 4 );

   /* Boucle pour toujours */    
   while ( 1 )
   {
      /* Allocation d'une structure T_message */    
      l_result = mk_pool_allocSafe ( g_pool, 
         ( T_mkAddr* ) &l_block, K_MK_POOL_CLEAR, 
         K_MK_TASK_WAIT_FOREVER );

      /* Si l'allocation a réussi */ 
      if ( l_result == K_MK_OK ) 
      {
         /* Écriture du message à envoyer */ 
         l_block->id = 1;
         l_block->value = l_counter++;

         /* Réinitialisation du compteur */ 
         if ( l_counter == 4 ) l_counter = 0;

         /* Transfert de l'adresse de l_block */
         l_result = mk_mail_post ( g_mail, &l_block, 
            K_MK_STATE_READY, K_MK_TASK_WAIT_FOREVER );

         /* Si une erreur s'est produite */   
         if ( l_result != K_MK_OK ) {
            /* Libération du bloc */
            l_result = mk_pool_freeSafe ( g_pool, l_block );
         }
      }
   }
}

/* Tâche consommatrice */
void mk_consumer ( T_mkAddr p_param )
{
   /* Dans cet exemple, le producteur est plus prioritaire  */
   /* que le consommateur. */
   /* La boîte est donc déjà initialisée quand le consommateur démarre. */
   T_mkCode l_result = K_MK_OK;
   T_message* l_received = K_MK_NULL;

   /* Boucle pour toujours */   
   while ( 1 )
   {
      /* Récupération du message */ 
      l_result = mk_mail_pend ( K_MK_NULL, g_mail, 
         &l_received, K_MK_TASK_WAIT_FOREVER );

      /* Si aucune erreur ne s'est produite */   
      if ( l_result == K_MK_OK ) {
            
         /* Utilisation de la donnée pointée ... */

         /* Libération du bloc */
         l_result = mk_pool_freeSafe ( g_pool, l_received );
      }
   }
}

La fonction mk_mail_post peut être appelée depuis un vecteur d'interruption pour transférer des données à une tâche :

void IRQHandler ( void )
{
   /* Le message est copié dans la boîte avant le retour de mk_mail_post */
   /* Une variable locale peut donc être utilisée */
   T_message l_message = { 2, 0 };
   T_mkCode l_result;

   /* Timeout nul, l'état READY est obligatoire dans une ISR */
   l_result = mk_mail_post ( g_mail, &l_message, K_MK_STATE_READY, 0 );

   /* Si K_MK_ERROR_TIMEOUT, la boîte est pleine et le message est perdu */
   /* On ne peut pas attendre qu'un emplacement se libère dans une ISR */
   ( void ) l_result;
}

Étant donné que le message est copié dans la boîte avant que la fonction mk_mail_post se termine, celui-ci n'a pas besoin d'être dans un contexte persistant. Il peut directement être stocké dans une variable locale.

La dernière fonction de l'API est la fonction mk_mail_delete. Elle permet de détruire la boîte de messages en demandant au noyau de la désallouer :

/* Suppression de la boîte de messages */
T_mkCode l_result = mk_mail_delete ( g_mail );

/* Si une erreur s'est produite */
if ( l_result != K_MK_OK )
{
   /* Gestion des erreurs ...  */
   /* K_MK_ERROR_PARAM, K_MK_ERROR_ISR, K_MK_ERROR_RIGHT */
}

4. Protéger ses boîtes de messages

Les boîtes de messages peuvent être créées avec les attributs K_MK_AREA_PROTECTED ou K_MK_AREA_UNPROTECTED.

Lorsque l'attribut K_MK_AREA_PROTECTED est utilisé, il est impossible pour une tâche non privilégiée de créer ou de manipuler une boîte. Une boîte non protégée doit donc être utilisée pour échanger des données entre les mondes privilégié et non privilégié.

Les règles de placement mémoire de la boîte ainsi que les erreurs de dimensionnement à éviter sont détaillées dans l'article Protéger son programme avec Mk. Les points suivants sont à retenir :

• ✔Les buffers fournis par une tâche non privilégiée doivent être situés en mémoire non privilégiée afin de ne pas faire échouer l'appel système.
• ✔Les buffers fournis par une tâche privilégiée ne sont pas contrôlés par le noyau. Leur taille doit être au moins égale à celle d'un message pour ne pas ouvrir une faille de sécurité.

Le tableau ci-dessous résume les règles de placement d'une boîte de messages non protégée :

5. API

T_mkCode mk_mail_create ( T_mkMail** p_mkMail, uint32_t p_mkAreaType, 
   T_mkPoolArea* p_mkMsgArea, uint32_t p_mkMsgSize, 
	uint32_t p_mkMsgNumber );
                  

T_mkCode mk_mail_post ( T_mkMail* p_mkMail, T_mkAddr p_mkMessage, 
	uint32_t p_mkState, uint32_t p_mkTick );
                  

T_mkCode mk_mail_pend ( T_mkTask** p_mkTask, T_mkMail* p_mkMail, 
	T_mkAddr p_mkMessage, uint32_t p_mkTick );
                  

T_mkCode mk_mail_delete ( T_mkMail* p_mkMail );