/* * Copyright (c) 2012-2013 The Linux Foundation. All rights reserved. * * Previously licensed under the ISC license by Qualcomm Atheros, Inc. * * * Permission to use, copy, modify, and/or distribute this software for * any purpose with or without fee is hereby granted, provided that the * above copyright notice and this permission notice appear in all * copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE * AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR * PERFORMANCE OF THIS SOFTWARE. */ /* * This file was originally distributed by Qualcomm Atheros, Inc. * under proprietary terms before Copyright ownership was assigned * to the Linux Foundation. */ #if !defined( __VOS_LIST_H ) #define __VOS_LIST_H /**========================================================================= \file vos_list.h \brief virtual Operating System Services (vOSS) List APIs Definitions for vOSS Linked Lists API Lists are implemented as a doubly linked list. An item in a list can be of any type as long as the datatype contains a field of type vos_link_t. In general, a list is a doubly linked list of items with a pointer to the front of the list and a pointer to the end of the list. The list items contain a forward and back link. List Nodes ============= =========================== +-------+ | Front |------------->+---------+ +---------+ +-------+ | Next |---->| Next |---->NULL | Back |-+ +---------+ +---------+ +-------+ | NULL<----| Prev |<----| Prev | | +---------+ +---------+ | |User Data| |User Data| | +---------+ +---------+ | ^ | | +---------------------------------+ This linked list API is implemented with appropriate locking mechanisms to assure operations on the list are thread safe. ========================================================================*/ /* $Header$ */ /*-------------------------------------------------------------------------- Include Files ------------------------------------------------------------------------*/ #include #include #include /*-------------------------------------------------------------------------- Preprocessor definitions and constants ------------------------------------------------------------------------*/ /*-------------------------------------------------------------------------- Type declarations ------------------------------------------------------------------------*/ /*------------------------------------------------------------------------- Function declarations and documenation ------------------------------------------------------------------------*/ /**--------------------------------------------------------------------------- \brief vos_list_init() - initialize a vOS Linked List The \a vos_list_init() function initializes the specified linked list 'object'. Upon successful initialization, the state of the list becomes initialized and available for use through the other vos_list_xxx APIs. A list must be initialized by calling vos_list_init() before it may be used in any other lock functions. Attempting to initialize an already initialized list results in a failure. \param pList - pointer to the opaque list object to initialize \return VOS_STATUS_SUCCESS - list was successfully initialized and is ready to be used. VOS_STATUS_E_RESOURCES - System resources (other than memory) are unavailable to initilize the list VOS_STATUS_E_NOMEM - insufficient memory exists to initialize the list VOS_STATUS_E_BUSY - The implementation has detected an attempt to reinitialize the object referenced by list, a previously initialized, but not yet destroyed, list. VOS_STATUS_E_FAULT - pList is an invalid pointer. \sa vos_list_destroy() --------------------------------------------------------------------------*/ VOS_STATUS vos_list_init( vos_list_t *pList ); /**------------------------------------------------------------------------- \brief vos_list_destroy() - Destroy a vOSS List The \a vos_list_destroy() function shall destroy the list object referenced by pList. After a successful return from \a vos_list_destroy() the list object becomes, in effect, uninitialized. A destroyed lock object can be reinitialized using vos_list_init(); the results of otherwise referencing the object after it has been destroyed are undefined. Calls to vOSS list functions to manipulate the list such will fail if the list or has not been initialized or is destroyed. Therefore, don't use the list after it has been destroyed until it has been re-initialized. \param pLlist - pointer to the list object to be destroyed. \return VOS_STATUS_SUCCESS - list was successfully destroyed. VOS_STATUS_E_BUSY - The implementation has detected an attempt to destroy the object referenced by pList that is still has nodes. The list must be empty before it can be destroyed. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_FAULT - pList is an invalid pointer. \sa ----------------------------------------------------------------------------*/ VOS_STATUS vos_list_destroy( vos_list_t *pList ); /*-------------------------------------------------------------------------- \brief vos_list_lock() - Lock a vOSS List The \a vos_list_lock() function shall lock the list object to prevent other tasks from operating on this list. The list remains locked until a call to vos_list_unlock() is made. Each list function already operate within a critical section. However it is sometimes necessary to lock a list over a series of list function calls. For example, when one needs to search a node on a list and insert another node after it, one would want to lock this list for the entire process in case another task attempts to manipulate this list. \param pLlist - pointer to the list object to be locked. \return VOS_STATUS_SUCCESS - list was successfully locked. VOS_STATUS_E_FAULT - pList is an invalid pointer. \sa vos_list_unlock() ----------------------------------------------------------------------------*/ VOS_STATUS vos_list_lock( vos_list_t *pList ); /*-------------------------------------------------------------------------- \brief vos_list_unlock() - Unlock a vOSS List The \a vos_list_unlock() function shall unlock the list object to allow other tasks to use this list. This function is only called when the vos_list_lock() is previously called in the current task. \param pLlist - pointer to the list object to be unlocked. \return VOS_STATUS_SUCCESS - list was successfully unlocked. VOS_STATUS_E_FAULT - pList is an invalid pointer. \sa vos_list_lock() ----------------------------------------------------------------------------*/ VOS_STATUS vos_list_unlock( vos_list_t *pList ); /**--------------------------------------------------------------------------- \brief vos_list_insert_front() - insert node at front of a linked list The vos_list_insert_front() API will insert a node at the front of a properly initialized vOS List object. \param pList - Pointer to list object where the node will be inserted \param pNode - Pointer to the list node to be inserted into the list. \return VOS_STATUS_SUCCESS - list node was successfully inserted onto the front of the list. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_FAULT - pList is an invalid pointer or pNode is an invalid pointer. \sa --------------------------------------------------------------------------*/ VOS_STATUS vos_list_insert_front( vos_list_t *pList, vos_list_node_t *pNode ); /**--------------------------------------------------------------------------- \brief vos_list_insert_back() - insert node at back of a linked list The vos_list_insert_back() API will insert a node at the back of a properly initialized vOS List object. \param pList - Pointer to list object where the node will be inserted \param pNode - Pointer to the list node to be inserted into the list. \return VOS_STATUS_SUCCESS - list node was successfully inserted onto the back of the list. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_FAULT - pList is an invalid pointer or pNode is an invalid pointer. \sa --------------------------------------------------------------------------*/ VOS_STATUS vos_list_insert_back( vos_list_t *pList, vos_list_node_t *pNode ); /**--------------------------------------------------------------------------- \brief vos_list_insert_back_size() - insert node at back of a linked list and return the size AFTER the enqueue. This size is determined in a race free manner i.e. while the list is locked for the enqueue operation The vos_list_insert_back_size() API will insert a node at the back of a properly initialized vOS List object. \param pList - Pointer to list object where the node will be inserted \param pNode - Pointer to the list node to be inserted into the list. \param pSize - Pointer to a size variable, where the size of the list will be returned. \return VOS_STATUS_SUCCESS - list node was successfully inserted onto the back of the list. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_FAULT - pList is an invalid pointer or pNode is an invalid pointer. \sa --------------------------------------------------------------------------*/ VOS_STATUS vos_list_insert_back_size( vos_list_t *pList, vos_list_node_t *pNode, v_SIZE_t *pSize ); /**--------------------------------------------------------------------------- \brief vos_list_remove_front() - remove node at front of a linked list The vos_list_remove_front() API will remove a node at the front of a properly initialized vOS List object. \param pList - Pointer to list object where the node will be removed \param ppNode - Pointer to a pointer to the list node to be removed from the list. \return VOS_STATUS_SUCCESS - list node was successfully removed from the front of the list. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_EMPTY - The specified is empty so nodes cannot be removed. VOS_STATUS_E_FAULT - pList is an invalid pointer or ppNode is an invalid pointer. \sa vos_list_remove_back() --------------------------------------------------------------------------*/ VOS_STATUS vos_list_remove_front( vos_list_t *pList, vos_list_node_t **ppNode ); /**--------------------------------------------------------------------------- \brief vos_list_remove_back() - remove node at back of a linked list The vos_list_remove_back() API will remove a node at the back of a properly initialized vOS List object. \param pList - Pointer to list object where the node will be removed \param ppNode - Pointer to a pointer to the list node to be removed from the list. \return VOS_STATUS_SUCCESS - list node was successfully removed from the back of the list. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_EMPTY - The specified is empty so nodes cannot be removed. VOS_STATUS_E_FAULT - pList is an invalid pointer or ppNode is an invalid pointer. \sa vos_list_remove_back() --------------------------------------------------------------------------*/ VOS_STATUS vos_list_remove_back( vos_list_t *pList, vos_list_node_t **ppNode ); /*---------------------------------------------------------------------------- \brief vos_list_size() - return the size of of a linked list The vos_list_size() API will return the number of nodes on the given vOS List object. \param pList - Pointer to list object where the node will be counted \param pSize - Pointer to a size variable, where the size of the list will be returned. \return VOS_STATUS_SUCCESS - list size of the properly initialized vos list object has been returned. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_FAULT - pList or pSize are not valid pointers \sa --------------------------------------------------------------------------*/ VOS_STATUS vos_list_size( vos_list_t *pList, v_SIZE_t *pSize ); /**--------------------------------------------------------------------------- \brief vos_list_peek_front() - peek at the node at front of a linked list The vos_list_peek_front() API will return a pointer to the node at the front of a properly initialized vOS List object. The node will *not* be removed from the list. \param pList - Pointer to list object of the list to be 'peeked' \param ppNode - Pointer to a pointer to the list node that exists at the front of the list. \return VOS_STATUS_SUCCESS - list node at the front of the list was successfully returned. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_EMPTY - The specified is empty so nodes cannot be removed. VOS_STATUS_E_FAULT - pList or or ppNode is an invalid pointer. \sa vos_list_remove_back() --------------------------------------------------------------------------*/ VOS_STATUS vos_list_peek_front( vos_list_t *pList, vos_list_node_t **ppNode ); /**--------------------------------------------------------------------------- \brief vos_list_peek_back() - peek at the node at back of a linked list The vos_list_peek_back() API will return a pointer to the node at the back of a properly initialized vOS List object. The node will *not* be removed from the list. \param pList - Pointer to list object of the list to be 'peeked' \param ppNode - Pointer to a pointer to the list node that exists at the back of the list. \return VOS_STATUS_SUCCESS - list node at the back of the list was successfully returned. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_EMPTY - The specified is empty so nodes cannot be removed. VOS_STATUS_E_FAULT - pList or or ppNode is an invalid pointer. \sa vos_list_peek_back(), vos_list_remove_back(), vos_list_peek_front(), vos_list_remove_front() --------------------------------------------------------------------------*/ VOS_STATUS vos_list_peek_back( vos_list_t *pList, vos_list_node_t **ppNode ); /**--------------------------------------------------------------------------- \brief vos_list_peek_next() - peek at the node after the specified node The vos_list_peek_next() API will return a pointer to the node following the specified node on a properly initialized vOS List object. The node will *not* be removed from the list. \param pList - Pointer to list object of the list to be 'peeked' \param pNode - Pointer to the node that is being 'peeked' \param ppNode - Pointer to a pointer to the list node that follows the pNode node on the list. \return VOS_STATUS_SUCCESS - list node following pNode on the properly initialized list is successfully returned. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_EMPTY - The specified is empty so nodes cannot be removed. VOS_STATUS_E_FAULT - pList, pNode or ppNode is an invalid pointer. \sa vos_list_remove_back() --------------------------------------------------------------------------*/ VOS_STATUS vos_list_peek_next( vos_list_t *pList, vos_list_node_t *pNode, vos_list_node_t **ppNode ); /**--------------------------------------------------------------------------- \brief vos_list_peek_prev() - peek at the node before the specified node The vos_list_peek_prev() API will return a pointer to the node before the specified node on a properly initialized vOS List object. The node will *not* be removed from the list. \param pList - Pointer to list object of the list to be 'peeked' \param pNode - Pointer to the node that is being 'peeked' \param ppNode - Pointer to a pointer to the list node before the pNode node on the list. \return VOS_STATUS_SUCCESS - list node before pNode on the properly initialized list is successfully returned. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_EMPTY - The specified is empty so nodes cannot be removed. VOS_STATUS_E_FAULT - pList, pNode or ppNode is an invalid pointer. \sa vos_list_remove_back() --------------------------------------------------------------------------*/ VOS_STATUS vos_list_peek_prev( vos_list_t *pList, vos_list_node_t *pNode, vos_list_node_t **ppNode ); /**--------------------------------------------------------------------------- \brief vos_list_insert_before() - insert node at front of a specified list node The vos_list_insert_before() API will insert a node onto a properly initialized vOS List object in front of the specified list node. \param pList - Pointer to list object where the node will be inserted \param pNodeToInsert - Pointer to the list node to be inserted into the list. \param pNode - Pointer to the list node where pNodeToInsert will be inserted in front of. \return VOS_STATUS_SUCCESS - list node was successfully inserted onto the front of the list. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_FAULT - pList, pNodeToInsert, or pNode are invalid pointer(s) \sa --------------------------------------------------------------------------*/ VOS_STATUS vos_list_insert_before( vos_list_t *pList, vos_list_node_t *pNodeToInsert, vos_list_node_t *pNode ); /**--------------------------------------------------------------------------- \brief vos_list_insert_after() - insert node behind a specified list node The vos_list_insert_after() API will insert a node onto a properly initialized vOS List object after the specified list node. \param pList - Pointer to list object where the node will be inserted \param pNodeToInsert - Pointer to the list node to be inserted into the list. \param pNode - Pointer to the list node where pNodeToInsert will be inserted after. \return VOS_STATUS_SUCCESS - list node was successfully inserted onto the front of the list. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_FAULT - pList, pNodeToInsert, or pNode are invalid pointer(s) \sa --------------------------------------------------------------------------*/ VOS_STATUS vos_list_insert_after( vos_list_t *pList, vos_list_node_t *pNodeToInsert, vos_list_node_t *pNode ); /**--------------------------------------------------------------------------- \brief vos_list_remove_node() - remove specified node from vOS list list The vos_list_remove_node() API will remove a specified node from the properly initialized vOS List object. \param pList - Pointer to list object where the node will be removed \param ppNode - Pointer to the node to be removed from the list. \return VOS_STATUS_SUCCESS - list node was successfully removed from the list. VOS_STATUS_E_INVAL - The value specified by pList is not a valid, initialized list object. VOS_STATUS_E_EMPTY - The specified is empty so nodes cannot be removed. VOS_STATUS_E_FAULT - pList or pNodeToRemove is not a valid pointer \sa --------------------------------------------------------------------------*/ VOS_STATUS vos_list_remove_node( vos_list_t *pList, vos_list_node_t *pNodeToRemove ); #endif // __VOS_LIST_H