/*
                             *******************
******************************* C HEADER FILE *******************************
**                           *******************                           **
**                                                                         **
** project      : The C Kernel                                             ** 
** filename     : CKMBOX.H                                                 **
** version      : 2                                                        **
** last revised : August 22, 2004                                          **
**                                                                         **
*****************************************************************************
**                                                                         **
** Copyright (c) 1998-2004, P.K. van der Vlugt                             **
** All rights reserved.                                                    **
**                                                                         **
*****************************************************************************

Mailbox Resource module.

VERSION HISTORY:
----------------

Version     : 1
Date        : June 01, 2003
Revised by  : P.K. van der Vlugt
Description : Original version

Version     : 2
Date        : August 22, 2004
Revised by  : P.K. van der Vlugt
Description : * Changed module name to comply to new kernel module naming 
                convention.
*/

#ifndef _CKMBOX_INCLUDED
#define _CKMBOX_INCLUDED

/****************************************************************************/
/**                                                                        **/
/**                     MODULES USED                                       **/
/**                                                                        **/
/****************************************************************************/

#include "ckconfig.h"

/****************************************************************************/
/**                                                                        **/
/**                     DEFINITIONS AND MACROS                             **/
/**                                                                        **/
/****************************************************************************/

#define EmptyMsgQueue(id)       (Mbox[id].msgHead >= NR_OF_MSGS)

/****************************************************************************/
/**                                                                        **/
/**                     TYPEDEFS AND STRUCTURES                            **/
/**                                                                        **/
/****************************************************************************/

typedef struct
{
  bool  req;
  int8u msgHead;
  int8u msgTail;
  int8u qid;
  int8u mode;
}
MboxType;

/****************************************************************************/
/**                                                                        **/
/**                     EXPORTED VARIABLES                                 **/
/**                                                                        **/
/****************************************************************************/

#ifndef _CKMBOX_C_SRC

#if NR_OF_MBOXS > 0 && NR_OF_MSGS > 0
extern MboxType Mbox[NR_OF_MBOXS];
#endif

#endif

/****************************************************************************/
/**                                                                        **/
/**                     EXPORTED FUNCTIONS                                 **/
/**                                                                        **/
/****************************************************************************/

/****************************************************************************/
void MboxInit (void);
/****************************************************************************/
/*
 * Initializes all resources in this module. This function must be called
 * before any other functions of this module are used. 
 */

/****************************************************************************/
int8u MboxAlloc (void);
/****************************************************************************/
/*
 * This function requests one of the available resources. If a resource
 * is available, the resource id will be returned. If there are no more
 * resources avaliable, NR_OF_MBOXS will be returned to indicate the
 * error situation. Other errors also return NR_OF_MBOXS.
 */

/****************************************************************************/
void MboxFree (int8u id);
/****************************************************************************/
/*
 * This function releases the specified resource id when it is a valid id. 
 * The resource is set back to the initial state. All associated resources 
 * (task queue and message resources) are also released.
 */

/****************************************************************************/
int8u EnqueueMsg (int8u id, int32u msg);
/****************************************************************************/
/*
 * Enqueues a message in the mailbox specified by id. The message is
 * allocated from the message resource pool and the 4-byte information
 * passed by msg is copied into the allocated message after which
 * the message is enqueued at the tail of the mailbox message queue.
 * If some error occurs, e.g. the message could not be allocated, the value
 * NR_OF_MSGS will be returned. If no errors occur the message id is returned.
 */

/****************************************************************************/
int8u DequeueMsg (int8u id, int32u *msgPtr);
/****************************************************************************/
/*
 * Dequeues a message from the mailbox specified by id. The message is
 * released to the message resource pool and the 4-byte information
 * pointed to by msgPtr is filled with the information from the message. A
 * message is dequeued from the head of the mailbox message queue.
 * If some error occurs, e.g. the message was already empty, the value
 * NR_OF_MSGS will be returned. If no errors occur the message id is returned.
 */

#endif

/****************************************************************************/
/**                                                                        **/
/**                               EOF                                      **/
/**                                                                        **/
/****************************************************************************/