mplutil.c

NATIONAL公司DP83816芯片Linux下驱动

//******************************************************************************
//
//  MPLUTIL.C
//
//  Copyright (c) 2004 National Semiconductor Corporation.
//  All Rights Reserved
//
//  Some utilities functions
//
//  This file contains the API implementations for
//     o Linked List management
//
//******************************************************************************

#include <mplinternal.h>

// Local functions


// List library APIs
//*****************************************************************************
//  MplListInit
//
//  Clients should use this API to initialize a linked list
//  
//  Parameters
//     list
//        A pointer to the MPL_LIST structure
//     safe
//        NS_TRUE  : If the list should be protected with locks
//                The list is implicitly protected only for MplListAddXXX 
//                and MplListDel APIs. The client needs to explicitly protect 
//                using MPL_LIST_LOCK and MPL_LIST_UNLOCK APIs for list 
//                traversal
//        NS_FALSE : If the list is unprotected
//
//  Return Value
//     NS_STATUS_SUCCESS : If the init was successful
//     NS_STATUS_RESOURCES: If the init failed due to mem
//
//*****************************************************************************
MPL_STATUS
   MplListInit(
      IN MPL_LIST *list,
      IN NS_BOOLEAN safe)
{
   MPL_STATUS ret = NS_STATUS_SUCCESS;

   // Init
   list->next = list->prev = (MPL_LIST_NODE *)list;
   list->entries = 0x0;
   list->lock = NULL;

   // Allocate lock if required
   if (safe == NS_TRUE)
   {
      if (OaiCreateLock(&list->lock) == NS_FALSE)
         ret = NS_STATUS_RESOURCES;
   }

   return ret;
}

//*****************************************************************************
//  MplListInit
//
//  Clients should use this API to de-initialize a linked list
//  
//  Parameters
//     list
//        A pointer to the MPL_LIST structure
//
//  Return Value
//
//*****************************************************************************
NS_VOID
   MplListDeInit(
      IN MPL_LIST *list)
{
   // Destory lock if we had one
   if (list->lock)
      OaiDestroyLock(list->lock);

   list->lock = NULL;
}

static __inline NS_VOID 
   listAdd(
      IN MPL_LIST_NODE *newNode,
      IN MPL_LIST_NODE *prev,
      IN MPL_LIST_NODE *next)
{
   next->prev = newNode;
   newNode->next  = next;
   newNode->prev  = prev;
   prev->next = newNode;
}

//*****************************************************************************
//  MplListAddHead
//
//  Clients should use this API to add a new node to the head of the list
//  This is used for stack data-structures
//  
//  Parameters
//     list
//        Pointer to the MPL_LIST structure
//     newNode
//        Pointer to the new node (MPL_LIST_NODE)
//
//  Return Value
//
//*****************************************************************************
NS_VOID
   MplListAddHead(
      IN MPL_LIST *list,
      IN MPL_LIST_NODE *newNode)
{
   MPL_LIST_LOCK(list);
   listAdd(newNode, (MPL_LIST_NODE *)list, list->next);
   list->entries++;
   MPL_LIST_UNLOCK(list);
}

//*****************************************************************************
//  MplListAddTail
//
//  Clients should use this API to add a new node to the tail of the list
//  This is used for queue data-structures
//  
//  Parameters
//     list
//        Pointer to the MPL_LIST structure
//     newNode
//        Pointer to the new node (MPL_LIST_NODE)
//
//  Return Value
//
//*****************************************************************************
NS_VOID
   MplListAddTail(
      IN MPL_LIST *list,
      IN MPL_LIST_NODE *newNode)
{
   MPL_LIST_LOCK(list);
   listAdd(newNode, list->prev, (MPL_LIST_NODE *)list);
   list->entries++;
   MPL_LIST_UNLOCK(list);
}

static __inline NS_VOID 
   listDel(
      IN MPL_LIST_NODE *prev,
      IN MPL_LIST_NODE *next)
{
   next->prev = prev;
   prev->next = next;
}

//*****************************************************************************
//  MplListDel
//
//  Clients should use this API to delete a node from the list
//  
//  Parameters
//     list
//        Pointer to the MPL_LIST structure
//     node
//        Pointer to the node (MPL_LIST_NODE)
//
//  Return Value
//
//*****************************************************************************
NS_VOID
   MplListDel(
      IN MPL_LIST *list,
      IN MPL_LIST_NODE *node)
{
   MPL_LIST_LOCK(list);
   listDel(node->prev, node->next);
   list->entries--;
   node->next = node->prev = NULL;
   MPL_LIST_UNLOCK(list);
}

//*****************************************************************************
//  MplListExample
//
//  Refer to the below code for an example of howto use the MPL list APIs
//  
//*****************************************************************************
#if 0

// Client's Overall context data structure 
// Below is an example only. The only thing needed is a MPL_LIST entry
typedef struct _EXP_CONTEXT{
   NS_UINT8 x;    // Client specific crap
   NS_UINT y;     // Client specific crap
   MPL_LIST list; // list entry - Required
} EXP_CONTEXT;

// Node data structure - The list is created of these structures
// Below is an example only. The only thing needed is a MPL_LIST_NODE entry
typedef struct _EXP_PARENT {
   NS_UINT8 x;         // Client specific crap
   NS_UINT y;          // Client specific crap
   MPL_LIST_NODE link; // Field for the list library to work on - Required
} EXP_PARENT;

NS_VOID listExample(EXP_CONTEXT ctx)
{
   EXP_PARENT par, *tmp;
   MPL_LIST_NODE *node;

   // Initialize a protected list (for unprotected pass NS_FALSE below)
   MplListInit(&ctx->list, NS_TRUE);

   // Add a new node to head - for stack implementation
   MplListAddHead(&ctx->list, &par->link);

   // Add a new node to tail - for queue implementation
   MplListAddTail(&ctx->list, &par->link);

   // List traversal - take locks for traversal
   MPL_LIST_LOCK(&ctx->list);
   for (node = MPL_LIST_GET_HEAD(&ctx->list); 
           MPL_LIST_CHK_END(&ctx->list, node) == NS_FALSE; 
               node = MPL_LIST_GET_NEXT(node))
   {
                             //Node, Type      , Member in parent data-structure
      tmp = MPL_LIST_GET_ENTRY(node, EXP_PARENT, link);
   }
   MPL_LIST_UNLOCK(&ctx->list);

   // Delete a node
   MplListDel(&ctx->list, &par->link);

   // De-Initialize the list 
   MplListDeInit(&ctx->list);
}
#endif