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

Queue 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 _CKQUEUE_INCLUDED
#define _CKQUEUE_INCLUDED

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

#include "ckconfig.h"

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

/**** Number of entries to use for queues ****/
#define NR_OF_QENTRIES  (NR_OF_TASKS + NR_OF_QUEUES * 2)

/**** Inline queue/list manipulation procedures ****/
#define Head(qid)       (NR_OF_TASKS + (int16u) qid * 2)
#define Tail(qid)       (NR_OF_TASKS + 1 + (int16u) qid * 2)

#define IsEmpty(qid)    (Q[Head (qid)].qnext >= NR_OF_TASKS)
#define NonEmpty(qid)   (Q[Head (qid)].qnext < NR_OF_TASKS)
#define FirstKey(qid)   (Q[Q[Head (qid)].qnext].qkey)
#define LastKey(qid)    (Q[Q[Tail (qid)].qprev].qkey)
#define FirstId(qid)    (Q[Head (qid)].qnext)

#define LIST_EMPTY      0xFF

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

typedef struct
{
  /**** Key on which the queue is ordered ****/  
  int16u qkey;
  /**** Pointer management ****/
  int16u qnext;
  int16u qprev;
}
QueueType;

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

#ifndef _CKQUEUE_C_SRC

extern QueueType Q[NR_OF_QENTRIES];

#endif

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

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

/****************************************************************************/
int8u QueueAlloc (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_QUEUES will be returned to indicate the
 * error situation. Other errors also return NR_OF_QUEUES.
 */

/****************************************************************************/
void QueueFree (int8u id);
/****************************************************************************/
/*
 * This function releases the specified resource id when it is a valid id. 
 * The resource is set back to the initial state. 
 */

/****************************************************************************/
void Enqueue (int8u qid, int8u tid);
/****************************************************************************/
/*
 * This function enqueues the task id at the tail of a list. This function
 * is normally used with FIFO queues: items are enqueued at the tail of a
 * list and are removed from the head of a list (using GetFirst).
 */

/****************************************************************************/
void Dequeue (int8u tid);
/****************************************************************************/
/*
 * This function dequeues the task id from any list. This function can be
 * used with both FIFO and priority queues.
 */

/****************************************************************************/
void Insert (int8u qid, int8u tid, int16u key);
/****************************************************************************/
/*
 * This function inserts a task in the list according to the key specified.
 * The highest key can be found at the tail of the list, so for priority
 * queues, use GetLast. From the priority perspective, equal keys are
 * inserted at the tail of the equal key group.
 */

/****************************************************************************/
int8u GetFirst (int8u qid);
/****************************************************************************/
/*
 * Return and remove the first task from the head of a list. This function
 * is normally used with FIFO queue (see Enqueue).
 */

/****************************************************************************/
int8u GetLast (int8u qid);
/****************************************************************************/
/*
 * Return and remove the last task from the tail of a list. This function
 * is normally used with priority queues (see also Insert).
 */

/****************************************************************************/
void InsertDelta (int8u qid, int8u tid, int16u key);
/****************************************************************************/
/*
 * This function inserts a task in the delta-list according to the key
 * specified.
 */

/****************************************************************************/
void DeleteDelta (int8u tid);
/****************************************************************************/
/*
 * This function deletes a task from the delta-list.
 */

#endif

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