fdi_que.h

Flash file system

    FM3-163
    1900 Prairie City Road
    Folsom, CA 95630

    Atten: Flash S/W License

Intel reserves the right to use and/or include Your name in 
public relations activities and marketing material and may 
request You to submit endorsements for the Software.  If You 
wish to discuss participation in this program, please send a 
fax to 916-356-2803 attn: "Software Marketing" with contact 
information and an Intel representative will contact You.

Revised: 02/16/01
***************************************************************************/ 

/* ### Include Files
 * ################################# */

#ifndef __QUEUE_H                      /* sentry header */
#define __QUEUE_H

#include "fdi_ext.h"
/* Option for local malloc/free */
#define   FDI_MALLOC(x)   Q_Alloc(x)
#define   FDI_FREE(x)     Q_Free(x)
#define   GET_FIRST_ITEM     0xff      /* input for priority in Q_Peek to pend
                                        * on items in the queue and get a
                                        * pointer to the first item. */

/* ### Error Codes:
 * ###
 * ### This defines an enumerated type, Q_ERROR, which is the return value
 * ### from several queue functions.  Applications using the queue library
 * ### should reference specific errors by using the symbols defined below.
 * ######################################################################## */

typedef enum
{
   Q_ERR_NONE = 0,
   Q_ERR_INVALID_HANDLE,
   Q_ERR_INVALID_SIZE,
   Q_ERR_NO_MEMORY,
   Q_ERR_NO_PRIORITY,
   Q_ERR_NO_ITEM,
   Q_ERR_SEMAPHORE,
   Q_ERR_NO_SPACE,
   Q_ERR_EMPTY,
   Q_ERR_PARAM
}  Q_ERROR;


/* ### This data type will be the value returned by Q_Create(), which will
 * ### be used in subsequent calls to identify which queue to access.  It
 * ### may seem rather pointless to return a pointer to void, but it would
 * ### be better if applications didn't know anything about the library's
 * ### internal data structures.  The queue library functions have a way
 * ### of determining whether a queue ID is valid or not, so it shouldn't
 * ### be a problem if an application accidentally submits a bad pointer.
 * ######################################################################## */
typedef void *Q_ID;
typedef Q_ID *Q_ID_PTR;

/*
 * Queue status information
 */
typedef enum
{
   Q_EMPTY,
   Q_NOT_EMPTY
}  Q_STATUS;

/* ### Compile-time Options:
 * ######################################################################## */

/* Queue align checking is not complete, make it false */
#define   Q_ALIGN_CHECKING   FALSE      /* Setting this option to TRUE     */
 /* causes the queue code to check  */
 /* the start address of the queue memory to ensure that it is   */
 /* DWORD aligned.  This checking applies to both the memory     */
 /* that is provided by the calling function, and any memory     */
 /* that is allocated by the queue code itself.  If it can be    */
 /* guaranteed that the application and/or MALLOC functions will */
 /* always provide memory that begins on a DWORD boundary, this  */
 /* option can be set to FALSE to reduce code size.              */

#define   Q_VERIFICATION    TRUE       /* When this option is set to      */
 /* TRUE, the queue functions will  */
 /* verify the validity of a queue (based on the Q_ID passed in) */
 /* before attempting to perform any operations on the queue.    */
 /* This option is useful for debugging, but can be disabled     */
 /* once the application is working properly.  Disabling this    */
 /* option will save a few bytes of RAM, as well as slightly     */
 /* decrease the code size and improve performance.              */

#define   Q_ERROR_CHECKING  TRUE       /* When this option is enabled,    */
 /* the queue will perform internal */
 /* error checking on itself and all input parameters passed in. */
 /* This option is useful for debugging, but can be disabled     */
 /* once the application is working properly, to decrease code   */
 /* size and to improve performance.                             */


/*
 * Queue Item Info Structure Definition
 */
typedef struct Q_ITEM
{
   struct Q_ITEM *next_item_ptr;       /* points to next item structure */
   WORD item_size;                     /* size of item data tagged below */
   BYTE pad1, pad2;   
}
Q_ITEM_INFO;

typedef Q_ITEM_INFO *Q_ITEM_PTR;

/*
 * Queue Priority Header Structure Definition
 */
typedef struct Q_HEADER
{
   struct Q_HEADER *next_header_ptr;   /* points to lower priority header */
   Q_ITEM_PTR first_item_ptr;          /* points to first item structure */
   WORD accum_free;                    /* accumulated free flash space in Q */
   WORD accum_dirty;                   /* accumulated dirty flash space in Q */
   BYTE priority;                      /* priority of item in queue */
   BYTE pad1, pad2, pad3;
}
Q_PRIORITY_HEADER;

typedef Q_PRIORITY_HEADER *Q_HDR_PTR;

/*
 * Queue Descriptor Structure Definition
 */
typedef struct Q_DESCRIPTOR
{
   SEM_ID sem_cntrl_sync;              /* true when an item is in queue */
   SEM_MTX_ID sem_cntrl_mutex;         /* mutex queue protection */
   Q_HDR_PTR first_header_ptr;         /* points to first priority header */
   BYTE alignment_shift;               /* for DWORD boundary alignment */
   BYTE number_items;                  /* number of items in queue */
   WORD free_count;                    /* number of free bytes */
#if (Q_VERIFICATION == TRUE)
   WORD queue_id;
   WORD queue_signature;
#endif
}
Q_DESCRIPTOR;

typedef Q_DESCRIPTOR *Q_DESC_PTR;

/*E.5.0.603.START*/
/* define these semaphores for static creation by GSM_MS initialization */
#if(SEM_CREATE_DESTROY == FALSE)
   extern SEM_ID SEM_cntrl_sync;              /* true when an item is in queue */
   extern SEM_MTX_ID SEM_cntrl_mutex;         /* mutex queue protection */
#endif
/*E.5.0.603.END*/

/* ### Global Functions
 * ################################# */



/* ### Function Prototypes:
 * ###
 * ###
 * ######################################################################## */

/* Q_Create - Creates a new message queue and allocates resources for it
 * usage: queue_id = Q_Create(q_size, RAM_ADDRESS, &q_status);
 *   or   queue_id = Q_Create(q_size, NULL, &q_status);
 */
Q_ID Q_Create(WORD, VOID_PTR, Q_ERROR *);

/* Q_Remove - Removes a message from a queue
 * usage: q_status = Q_Remove(queue_id, data_ptr, append_to_replace_flag);
 */
Q_ERROR Q_Remove(Q_ID, VOID_PTR, BYTE);

/* Q_Delete - Deletes a message queue and frees all resources used by it
 * usage: q_status = Q_Delete(queue_id);
 */
Q_ERROR Q_Delete(Q_ID);

/* Q_Peek   - Retrieves the address and size of a message in a queue
 * usage: q_status = Q_Peek(queue_id, &data_ptr, &size, priority);
 * or     q_status = Q_Peek(queue_id, &data_ptr, &size, GET_FIRST_ITEM);
 */
Q_ERROR Q_Peek(Q_ID, VOID_PTR_PTR, WORD_PTR, BYTE);

/* Q_Add    - Places a new message into a queue
 * usage: q_status = Q_Add(queue_id, data1_ptr, data2_ptr, data1_size,
                           data2_size, priority, append_to_replace_flag);
 */
Q_ERROR Q_Add(Q_ID, const VOID *, const VOID *, WORD, WORD, BYTE, BYTE);

/* Q_Status    - Returns a status indicator that tells if there is an item in
                 the queue or not.
 * usage: q_status = Q_Status(queue_id);
 */
Q_ERROR Q_Status(Q_ID);

/* Q_GetAccumSize - Gets the needed space requirements of the items in the Q
 * usage: Q_GetAccumSize(queue_id, &free_space, &dirty_spce, priority);
 */
/*void Q_GetAccumSize(Q_ID, WORD_PTR, WORD_PTR, BYTE);*/
/* Q_GetAccumSize - Gets the needed space requirements of the items in the Q
 * usage: Q_GetAccumSize(queue_id, &free_space, &dirty_spce);
 */
void Q_GetAccumSize(Q_ID, WORD_PTR, WORD_PTR);

/* Local memory allocation/free prototypes */
BYTE * Q_Alloc (WORD size);
void  Q_Free  (const BYTE *addr);

#endif                                 /* sentry */