source: trunk/kernel/libk/spinlock.h @ 9

Last change on this file since 9 was 1, checked in by alain, 8 years ago

First import
File size: 6.4 KB
RevLine 
[1]1/*
2 * spinlock.h: kernel spinlock definition     
3 *
4 * Authors  Ghassan Almaless (2008,2009,2010,2011,2012)
5 *          Alain Greiner    (2016)
6 *
7 * Copyright (c) UPMC Sorbonne Universites
8 *
9 * This file is part of ALMOS-MKH.
10 *
11 * ALMOS-MKH is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; version 2.0 of the License.
14 *
15 * ALMOS-MKH is distributed in the hope that it will be useful, but
16 * WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18 * General Public License for more details.
19 *
20 * You should have received a copy of the GNU General Public License
21 * along with ALMOS-kernel; if not, write to the Free Software Foundation,
22 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
23 */
24
25#ifndef _SPINLOCK_H_
26#define _SPINLOCK_H_
27
28#include <almos_config.h>
29#include <hal_types.h>
30#include <list.h>
31
32/*******************************************************************************************
33 * This structure defines a local spinlock, that sequencializes all read or write accesses
34 * in a given cluster. A new access can only start after completion of the previous access,
35 * when the owner thread releases the lock. The lock has only two states: taken or free.
36 * The owner thread is registered in the spinlock_t structure, and the calling thread
37 * list of local spinlocks is updated.
38 *
39 * A spinlock can be accessed in three modes :
40 *
41 * - The spinlock_lock() function is BLOCKING and use a descheduling policy when the lock
42 *   is already taken. The lock must be released with the spinlock_unlock() function.
43 * - The spinlock_lock_noirq() function is BLOCKING, but uses a polling (busy-waiting)
44 *   policy if the lock is already taken. The IRQs can be disabled or not depending
45 *   on the irq_state argument. The lock must be released with the spinlock_unlock_noirq()
46 *   function.
47 * - The spinlock_trylock() function is NON-BLOCKING, and tries only once to take the lock.
48 *   It must be released with the spinlock_unlock() function.
49 ******************************************************************************************/
50
51/****     Forward declarations    ****/
52
53struct thread_s;
54
55/*******************************************************************************************
56 * This structure defines a local spinlock.
57 ******************************************************************************************/
58
59typedef struct spinlock_s
60{
61        uint32_t            taken;             /*! state : free if zero / taken if non zero  */
62        struct thread_s   * owner;             /*! pointer on curent owner thread            */
63    list_entry_t        list;              /*! list of all locks taken by owner          */
64}
65spinlock_t;
66
67/*******************************************************************************************
68 * This function initializes a local spinlock in free state.
69 *******************************************************************************************
70 * @ lock    : pointer on spinlock.
71 ******************************************************************************************/
72inline void spinlock_init( spinlock_t * lock );
73
74/*******************************************************************************************
75 * This blocking function uses a busy waiting strategy to lock a local spinlock.
76 * It polls the lock and returns only when the lock has been taken.
77 * If the irq_state argument is not NULL, all IRQs are disabled and will keep disabled
78 * until the lock is released. If irq_state is NULL, the IRQs are only disabled
79 * during the lock acquisition polling loop.
80 * It increments the calling thread local_locks count when the lock has been taken.
81 *******************************************************************************************
82 * @ lock       : pointer on spinlock
83 * @ irq_state  : buffer to save the SR state (in the calling thread stack)
84 ******************************************************************************************/
85void spinlock_lock_busy( spinlock_t * lock,
86                         uint32_t   * irq_state );
87
88/*******************************************************************************************
89 * This function releases a local busy_waiting spinlock.
90 * It restores the CPU SR state, if required by the restore argument.
91 *******************************************************************************************
92 * @ lock       : pointer on spinlock
93 * @ restore    : restore the CPU SR (from irq_state) if true
94 * @ irq_state  : value to be resrored in CPU SR
95 ******************************************************************************************/
96void spinlock_unlock_busy( spinlock_t * lock,
97                           bool_t       restore,
98                           uint32_t     irq_state );
99
100/*******************************************************************************************
101 * This blocking function locks a local spinlock.
102 * If the lock is already taken, the calling thread deschedules and retries when
103 * it is rescheduled, until success.
104 * It increments the calling thread local_locks count when the lock has been taken.
105 *******************************************************************************************
106 * @ lock       : pointer on spinlock
107 ******************************************************************************************/
108void spinlock_lock( spinlock_t * lock );
109
110/*******************************************************************************************
111 * This non-blocking function tries once to lock a spinlock.
112 * It increments the calling thread locks count in case of success.
113 *******************************************************************************************
114 * @ lock       : pointer on spinlock
115 * @ returns 0 if success / returns non zero if lock already taken.
116 ******************************************************************************************/
117uint32_t spinlock_trylock( spinlock_t * lock );
118
119/*******************************************************************************************
120 * This function releases a spinlock and do schedule if necessary.
121 *******************************************************************************************
122 * @ lock       : pointer on spinlock
123 ******************************************************************************************/
124void spinlock_unlock( spinlock_t * lock );
125
126
127#endif  /* _SPINLOCK_H_ */
Note: See TracBrowser for help on using the repository browser.