fdi_que.h

FDI Intel开发的FLASH文件系统,功能很强大

/* ###########################################################################
###  Intel Confidential 
###  Copyright (c) Intel Corporation 1995-2002
###  All Rights Reserved.
###  -------------------------------------------------------------------------
###  Project: Flash Data Integrator
###
###  Module: QUEUE.H - This module consists of all the queue definitions.
###
###  $Archive: /FDI/SRC/INCLUDE/fdi_que.h $
###  $Revision: 62 $
###  $Date: 6/16/03 4:10a $
###  $Author: Xhuang4 $
###  $NoKeywords $
########################################################################### */

/*                                                               
 *****************************************************************
 * NOTICE OF LICENSE AGREEMENT                                    
 *                                                                
 * This code is provided by Intel Corp., and the use is governed  
 * under the terms of a license agreement. See license agreement  
 * for complete terms of license.                                 
 *                                                                
 * YOU MAY ONLY USE THE SOFTWARE WITH INTEL FLASH PRODUCTS.  YOUR 
 * USE OF THE SOFTWARE WITH ANY OTHER FLASH PRODUCTS IS EXPRESSLY 
 * PROHIBITED UNLESS AND UNTIL YOU APPLY FOR, AND ARE GRANTED IN  
 * INTEL'S SOLE DISCRETION, A SEPARATE WRITTEN SOFTWARE LICENSE   
 * FROM INTEL LICENSING ANY SUCH USE.                             
 *****************************************************************
 */
 

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

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

/* E.5.0.690 Begin */ 
/*remove include fdi_ext.h ,add fdi_int.h*/
/*#include "fdi_ext.h"*/
#include "fdi_int.h"
/* E.5.0.690 End */ 

/* ### 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.                             */

/* E.5.1.762 Start */
#if (Q_ERROR_CHECKING == TRUE)
#define Q_MAX_SIZE ( sizeof(Q_DESCRIPTOR) + \
                     sizeof(Q_PRIORITY_HEADER) + \
                     (WORDMAX * (sizeof(COMMAND) + sizeof(Q_ITEM_INFO))) )

/*
 * This define is used to calculate the absolute minimum number of bytes
 * needed to implement a queue of two items of one byte in size.  If the
 * Q_ALIGN_CHECKING option is set, an extra three bytes will be added to
 * this value to allow for possible alignment shifting.
 */
/* Moved Q_MIN_SIZE from que.h */
#define   Q_MIN_SIZE  (sizeof(Q_DESCRIPTOR) + sizeof(Q_PRIORITY_HEADER) + \
                         (((sizeof(Q_ITEM_INFO) + 3) & Q_DWORD_MASK) * 2))
#endif
/* E.5.1.762 End */

/* E.5.0.690 Begin */
/*
 * Maximum number of queue items that can be in the queue at any given time.
 * Used to reserve allocation control arrays
 */
/*
 * Calculate the maximum number of queue items that is possible.  This is used
 * used to determine the size of, and manage, the queue control structures.
 * Two worst case possibilities exist: 1) All zero data COMMAND items w/
 * PRIORITY_HEADERs, 2) All zero data COMMAND items w/o PRIORITY_HEADERs.  If
 * the size of PRIORITY_HEADER is less than that of COMMAND plus
 * Q_ITEM_INFO, then case 1 is the worst case, otherwise case 2. Two or Three
 * is added to account for the q_descriptor and q_priority_header, plus 1 for
 * rounding.
 */ 
/* Add MAX_QUEUE_ITEMS definition here. */
/* E 5.1.849 START */
#define MAX_QUEUE_ITEMS ( (sizeof(Q_PRIORITY_HEADER) < (sizeof(COMMAND) + \
                         sizeof(Q_ITEM_INFO))) ? \
    ((((FDI_QUEUE_SIZE - sizeof(Q_DESCRIPTOR)) / \
                        (sizeof(Q_PRIORITY_HEADER) + \
                         sizeof(COMMAND) + \
                         sizeof(Q_ITEM_INFO))) * \
                         2) + \
                         2) : \
      (((FDI_QUEUE_SIZE - sizeof(Q_DESCRIPTOR)) - \
                         sizeof(Q_PRIORITY_HEADER)) / \
                        (sizeof(COMMAND) + \
                         sizeof(Q_ITEM_INFO)) + \
                         3) )
/* E 5.1.849 END */                       

/* E.5.0.690 End */ 

                         
/* 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;


/*
 * Queue Item Info Structure Definition
 */
/* E.5.0.708 START */
/* change PACKED to FDI_PACKED */
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;   
}
FDI_PACKED(Q_ITEM_INFO);
/* E.5.0.708 END */

typedef Q_ITEM_INFO *Q_ITEM_PTR;

/*
 * Queue Priority Header Structure Definition
 */
/* E.5.0.708 START */
/* change PACKED to FDI_PACKED */
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;
}
FDI_PACKED(Q_PRIORITY_HEADER);
/* E.5.0.708 END */

typedef Q_PRIORITY_HEADER *Q_HDR_PTR;

/*
 * Queue Descriptor Structure Definition
 */
/* E.5.0.708 START */
/* change PACKED to FDI_PACKED */
typedef struct Q_DESCRIPTOR
{
   /*E.5.0.702.Start*/
   /*change names to avoid confusion */
   SEM_ID sem_queue_cntrl_sync;              /* true when an item is in queue */
   SEM_MTX_ID sem_queue_cntrl_mutex;         /* mutex queue protection */
   /*E.5.0.702.End*/
   Q_HDR_PTR first_header_ptr;         /* points to first priority header */
/* E.5.1.762 Start */
   WORD number_items;                  /* number of items in queue */
/* E.5.1.762 End */
   WORD free_count;                    /* number of free bytes */
#if (Q_VERIFICATION == TRUE)
   WORD queue_id;
   WORD queue_signature;
#endif
/* E.5.1.762 Start */
#if (Q_ALIGN_CHECKING == TRUE)
   BYTE alignment_shift;               /* for DWORD boundary alignment */
   BYTE pad1, pad2, pad3;              /* Padded for DWORD allignment. */
#endif
/* E.5.1.762 End */
}
FDI_PACKED(Q_DESCRIPTOR);
/* E.5.0.708 END */

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);
 */
/* E.5.0.652 Begin */
Q_ERROR Q_Add(Q_ID, VOID *, VOID *, WORD, WORD, BYTE, BYTE);
/* E.5.0.652 End */

/* 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);
/* E.5.0.652 Begin */
void  Q_Free  (BYTE *addr);
/* E.5.0.652 End */

#endif                                 /* sentry */