OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [freertos-6.1.1/] [Source/] [include/] [list.h] - Blame information for rev 572

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 572 jeremybenn
/*
2
    FreeRTOS V6.1.1 - Copyright (C) 2011 Real Time Engineers Ltd.
3
 
4
    ***************************************************************************
5
    *                                                                         *
6
    * If you are:                                                             *
7
    *                                                                         *
8
    *    + New to FreeRTOS,                                                   *
9
    *    + Wanting to learn FreeRTOS or multitasking in general quickly       *
10
    *    + Looking for basic training,                                        *
11
    *    + Wanting to improve your FreeRTOS skills and productivity           *
12
    *                                                                         *
13
    * then take a look at the FreeRTOS books - available as PDF or paperback  *
14
    *                                                                         *
15
    *        "Using the FreeRTOS Real Time Kernel - a Practical Guide"        *
16
    *                  http://www.FreeRTOS.org/Documentation                  *
17
    *                                                                         *
18
    * A pdf reference manual is also available.  Both are usually delivered   *
19
    * to your inbox within 20 minutes to two hours when purchased between 8am *
20
    * and 8pm GMT (although please allow up to 24 hours in case of            *
21
    * exceptional circumstances).  Thank you for your support!                *
22
    *                                                                         *
23
    ***************************************************************************
24
 
25
    This file is part of the FreeRTOS distribution.
26
 
27
    FreeRTOS is free software; you can redistribute it and/or modify it under
28
    the terms of the GNU General Public License (version 2) as published by the
29
    Free Software Foundation AND MODIFIED BY the FreeRTOS exception.
30
    ***NOTE*** The exception to the GPL is included to allow you to distribute
31
    a combined work that includes FreeRTOS without being obliged to provide the
32
    source code for proprietary components outside of the FreeRTOS kernel.
33
    FreeRTOS is distributed in the hope that it will be useful, but WITHOUT
34
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
35
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
36
    more details. You should have received a copy of the GNU General Public
37
    License and the FreeRTOS license exception along with FreeRTOS; if not it
38
    can be viewed here: http://www.freertos.org/a00114.html and also obtained
39
    by writing to Richard Barry, contact details for whom are available on the
40
    FreeRTOS WEB site.
41
 
42
    1 tab == 4 spaces!
43
 
44
    http://www.FreeRTOS.org - Documentation, latest information, license and
45
    contact details.
46
 
47
    http://www.SafeRTOS.com - A version that is certified for use in safety
48
    critical systems.
49
 
50
    http://www.OpenRTOS.com - Commercial support, development, porting,
51
    licensing and training services.
52
*/
53
 
54
/*
55
 * This is the list implementation used by the scheduler.  While it is tailored
56
 * heavily for the schedulers needs, it is also available for use by
57
 * application code.
58
 *
59
 * xLists can only store pointers to xListItems.  Each xListItem contains a
60
 * numeric value (xItemValue).  Most of the time the lists are sorted in
61
 * descending item value order.
62
 *
63
 * Lists are created already containing one list item.  The value of this
64
 * item is the maximum possible that can be stored, it is therefore always at
65
 * the end of the list and acts as a marker.  The list member pxHead always
66
 * points to this marker - even though it is at the tail of the list.  This
67
 * is because the tail contains a wrap back pointer to the true head of
68
 * the list.
69
 *
70
 * In addition to it's value, each list item contains a pointer to the next
71
 * item in the list (pxNext), a pointer to the list it is in (pxContainer)
72
 * and a pointer to back to the object that contains it.  These later two
73
 * pointers are included for efficiency of list manipulation.  There is
74
 * effectively a two way link between the object containing the list item and
75
 * the list item itself.
76
 *
77
 *
78
 * \page ListIntroduction List Implementation
79
 * \ingroup FreeRTOSIntro
80
 */
81
 
82
/*
83
        Changes from V4.3.1
84
 
85
        + Included local const within listGET_OWNER_OF_NEXT_ENTRY() to assist
86
          compiler with optimisation.  Thanks B.R.
87
*/
88
 
89
#ifndef LIST_H
90
#define LIST_H
91
 
92
#ifdef __cplusplus
93
extern "C" {
94
#endif
95
/*
96
 * Definition of the only type of object that a list can contain.
97
 */
98
struct xLIST_ITEM
99
{
100
        portTickType xItemValue;                                /*< The value being listed.  In most cases this is used to sort the list in descending order. */
101
        volatile struct xLIST_ITEM * pxNext;    /*< Pointer to the next xListItem in the list. */
102
        volatile struct xLIST_ITEM * pxPrevious;/*< Pointer to the previous xListItem in the list. */
103
        void * pvOwner;                                                 /*< Pointer to the object (normally a TCB) that contains the list item.  There is therefore a two way link between the object containing the list item and the list item itself. */
104
        void * pvContainer;                                             /*< Pointer to the list in which this list item is placed (if any). */
105
};
106
typedef struct xLIST_ITEM xListItem;            /* For some reason lint wants this as two separate definitions. */
107
 
108
struct xMINI_LIST_ITEM
109
{
110
        portTickType xItemValue;
111
        volatile struct xLIST_ITEM *pxNext;
112
        volatile struct xLIST_ITEM *pxPrevious;
113
};
114
typedef struct xMINI_LIST_ITEM xMiniListItem;
115
 
116
/*
117
 * Definition of the type of queue used by the scheduler.
118
 */
119
typedef struct xLIST
120
{
121
        volatile unsigned portBASE_TYPE uxNumberOfItems;
122
        volatile xListItem * pxIndex;                   /*< Used to walk through the list.  Points to the last item returned by a call to pvListGetOwnerOfNextEntry (). */
123
        volatile xMiniListItem xListEnd;                /*< List item that contains the maximum possible item value meaning it is always at the end of the list and is therefore used as a marker. */
124
} xList;
125
 
126
/*
127
 * Access macro to set the owner of a list item.  The owner of a list item
128
 * is the object (usually a TCB) that contains the list item.
129
 *
130
 * \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER
131
 * \ingroup LinkedList
132
 */
133
#define listSET_LIST_ITEM_OWNER( pxListItem, pxOwner )          ( pxListItem )->pvOwner = ( void * ) pxOwner
134
 
135
/*
136
 * Access macro to set the value of the list item.  In most cases the value is
137
 * used to sort the list in descending order.
138
 *
139
 * \page listSET_LIST_ITEM_VALUE listSET_LIST_ITEM_VALUE
140
 * \ingroup LinkedList
141
 */
142
#define listSET_LIST_ITEM_VALUE( pxListItem, xValue )           ( pxListItem )->xItemValue = xValue
143
 
144
/*
145
 * Access macro the retrieve the value of the list item.  The value can
146
 * represent anything - for example a the priority of a task, or the time at
147
 * which a task should be unblocked.
148
 *
149
 * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE
150
 * \ingroup LinkedList
151
 */
152
#define listGET_LIST_ITEM_VALUE( pxListItem )                           ( ( pxListItem )->xItemValue )
153
 
154
/*
155
 * Access macro to determine if a list contains any items.  The macro will
156
 * only have the value true if the list is empty.
157
 *
158
 * \page listLIST_IS_EMPTY listLIST_IS_EMPTY
159
 * \ingroup LinkedList
160
 */
161
#define listLIST_IS_EMPTY( pxList )                             ( ( pxList )->uxNumberOfItems == ( unsigned portBASE_TYPE ) 0 )
162
 
163
/*
164
 * Access macro to return the number of items in the list.
165
 */
166
#define listCURRENT_LIST_LENGTH( pxList )               ( ( pxList )->uxNumberOfItems )
167
 
168
/*
169
 * Access function to obtain the owner of the next entry in a list.
170
 *
171
 * The list member pxIndex is used to walk through a list.  Calling
172
 * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list
173
 * and returns that entries pxOwner parameter.  Using multiple calls to this
174
 * function it is therefore possible to move through every item contained in
175
 * a list.
176
 *
177
 * The pxOwner parameter of a list item is a pointer to the object that owns
178
 * the list item.  In the scheduler this is normally a task control block.
179
 * The pxOwner parameter effectively creates a two way link between the list
180
 * item and its owner.
181
 *
182
 * @param pxList The list from which the next item owner is to be returned.
183
 *
184
 * \page listGET_OWNER_OF_NEXT_ENTRY listGET_OWNER_OF_NEXT_ENTRY
185
 * \ingroup LinkedList
186
 */
187
#define listGET_OWNER_OF_NEXT_ENTRY( pxTCB, pxList )                                                                    \
188
{                                                                                                                                                                               \
189
xList * const pxConstList = pxList;                                                                                                             \
190
        /* Increment the index to the next item and return the item, ensuring */                        \
191
        /* we don't return the marker used at the end of the list.  */                                          \
192
        ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext;                                            \
193
        if( ( pxConstList )->pxIndex == ( xListItem * ) &( ( pxConstList )->xListEnd ) )        \
194
        {                                                                                                                                                                       \
195
                ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext;                                    \
196
        }                                                                                                                                                                       \
197
        pxTCB = ( pxConstList )->pxIndex->pvOwner;                                                                                      \
198
}
199
 
200
 
201
/*
202
 * Access function to obtain the owner of the first entry in a list.  Lists
203
 * are normally sorted in ascending item value order.
204
 *
205
 * This function returns the pxOwner member of the first item in the list.
206
 * The pxOwner parameter of a list item is a pointer to the object that owns
207
 * the list item.  In the scheduler this is normally a task control block.
208
 * The pxOwner parameter effectively creates a two way link between the list
209
 * item and its owner.
210
 *
211
 * @param pxList The list from which the owner of the head item is to be
212
 * returned.
213
 *
214
 * \page listGET_OWNER_OF_HEAD_ENTRY listGET_OWNER_OF_HEAD_ENTRY
215
 * \ingroup LinkedList
216
 */
217
#define listGET_OWNER_OF_HEAD_ENTRY( pxList )  ( ( pxList->uxNumberOfItems != ( unsigned portBASE_TYPE ) 0 ) ? ( (&( pxList->xListEnd ))->pxNext->pvOwner ) : ( NULL ) )
218
 
219
/*
220
 * Check to see if a list item is within a list.  The list item maintains a
221
 * "container" pointer that points to the list it is in.  All this macro does
222
 * is check to see if the container and the list match.
223
 *
224
 * @param pxList The list we want to know if the list item is within.
225
 * @param pxListItem The list item we want to know if is in the list.
226
 * @return pdTRUE is the list item is in the list, otherwise pdFALSE.
227
 * pointer against
228
 */
229
#define listIS_CONTAINED_WITHIN( pxList, pxListItem ) ( ( pxListItem )->pvContainer == ( void * ) pxList )
230
 
231
/*
232
 * Must be called before a list is used!  This initialises all the members
233
 * of the list structure and inserts the xListEnd item into the list as a
234
 * marker to the back of the list.
235
 *
236
 * @param pxList Pointer to the list being initialised.
237
 *
238
 * \page vListInitialise vListInitialise
239
 * \ingroup LinkedList
240
 */
241
void vListInitialise( xList *pxList );
242
 
243
/*
244
 * Must be called before a list item is used.  This sets the list container to
245
 * null so the item does not think that it is already contained in a list.
246
 *
247
 * @param pxItem Pointer to the list item being initialised.
248
 *
249
 * \page vListInitialiseItem vListInitialiseItem
250
 * \ingroup LinkedList
251
 */
252
void vListInitialiseItem( xListItem *pxItem );
253
 
254
/*
255
 * Insert a list item into a list.  The item will be inserted into the list in
256
 * a position determined by its item value (descending item value order).
257
 *
258
 * @param pxList The list into which the item is to be inserted.
259
 *
260
 * @param pxNewListItem The item to that is to be placed in the list.
261
 *
262
 * \page vListInsert vListInsert
263
 * \ingroup LinkedList
264
 */
265
void vListInsert( xList *pxList, xListItem *pxNewListItem );
266
 
267
/*
268
 * Insert a list item into a list.  The item will be inserted in a position
269
 * such that it will be the last item within the list returned by multiple
270
 * calls to listGET_OWNER_OF_NEXT_ENTRY.
271
 *
272
 * The list member pvIndex is used to walk through a list.  Calling
273
 * listGET_OWNER_OF_NEXT_ENTRY increments pvIndex to the next item in the list.
274
 * Placing an item in a list using vListInsertEnd effectively places the item
275
 * in the list position pointed to by pvIndex.  This means that every other
276
 * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before
277
 * the pvIndex parameter again points to the item being inserted.
278
 *
279
 * @param pxList The list into which the item is to be inserted.
280
 *
281
 * @param pxNewListItem The list item to be inserted into the list.
282
 *
283
 * \page vListInsertEnd vListInsertEnd
284
 * \ingroup LinkedList
285
 */
286
void vListInsertEnd( xList *pxList, xListItem *pxNewListItem );
287
 
288
/*
289
 * Remove an item from a list.  The list item has a pointer to the list that
290
 * it is in, so only the list item need be passed into the function.
291
 *
292
 * @param vListRemove The item to be removed.  The item will remove itself from
293
 * the list pointed to by it's pxContainer parameter.
294
 *
295
 * \page vListRemove vListRemove
296
 * \ingroup LinkedList
297
 */
298
void vListRemove( xListItem *pxItemToRemove );
299
 
300
#ifdef __cplusplus
301
}
302
#endif
303
 
304
#endif
305
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.