source: trunk/kernel/libk/remote_queuelock.h @ 590

Last change on this file since 590 was 563, checked in by alain, 6 years ago

Complete restructuration of kernel spinlocks.

File size: 5.0 KB
Line 
1/*
2 * remote_queuelock.h: remote kernel lock with waiting queue definition.
3 *
4 * Authors  Alain Greiner (2016,2017,2018)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-kernel; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _REMOTE_QUEUELOCK_H_
25#define _REMOTE_QUEUELOCK_H_
26
27#include <kernel_config.h>
28#include <hal_kernel_types.h>
29#include <remote_busylock.h>
30#include <xlist.h>
31
32/*******************************************************************************************
33 * This synchronisation object sequencializes concurrent read or write accesses to a
34 * globally shared object located in any cluster, made by thread(s) running in any cluster.
35 * This lock has only two states: taken or free.
36 * When the lock has been taken by another thread T', the thread T executing the
37 * queuelock_acquire() function blocks and deschedules, after registering in the waiting
38 * queue rooted in lock descriptor. The first thread in the waiting queue will be unblocked
39 * by the owner thread executing the queuelock_release() function.
40 * To handle concurrent accesses between a thread T executing the acquire() function
41 * and a thread T' executing the release() function, the "remote_queuelock" is protected
42 * by a "remote_busylock" used by these two access functions.
43 * WARNING: this remote_queuelock is NOT registered in the thread "remote_locks" field.
44 ******************************************************************************************/
45 
46
47/*******************************************************************************************
48 * This structure defines a remote_queuelock.
49 ******************************************************************************************/
50
51typedef struct remote_queuelock_s
52{
53    remote_busylock_t   lock;               /*! protect atomic access to remote_queuelock */
54        volatile uint32_t   taken;              /*! state : free if zero / taken if non zero  */
55    xlist_entry_t       xroot;              /*! root of xlist of waiting threads          */
56}
57remote_queuelock_t;
58
59/*******************************************************************************************
60 * This function initializes a local remote_queuelock in free state.
61 * The <name> argument defines the lock usage and is only used for debug.
62 * This type is actually stored in the associated busylock descriptor.
63 *******************************************************************************************
64 * @ lock_xp   : extended pointer on remote_queuelock.
65 * @ type      : lock usage for debug.
66******************************************************************************************/
67inline void remote_queuelock_init( xptr_t   lock_xp,
68                                   uint32_t type );
69
70/*******************************************************************************************
71 * This blocking function acquires a remote_queuelock.
72 * The calling thread and the lock can be in different clusters.
73 * It uses the remote_busylock to atomically access/update the remote_queuelock state.
74 * If the lock is already taken, the calling thread atomically registers in the xlist
75 * of waiting threads (rooted in the lock descriptor), block and deschedule.
76 * It increments the calling thread remote_locks counter when the lock has been taken.
77 * It optionally update the <owner_xp> and <xlist> debug fields.
78 *******************************************************************************************
79 * @ lock_xp   : extended pointer on remote_queuelock.
80 ******************************************************************************************/
81void remote_queuelock_acquire( xptr_t  lock_xp );
82
83/*******************************************************************************************
84 * This function releases a remote_queuelock.
85 * The calling thread and the lock can be in different clusters.
86 * It uses the remote_busylock to atomically access/update the remote_queuelock state.
87 * If the xlist of waiting threads is not empty, the first waiting thread is unblocked.
88 * It decrements the calling thread remote_locks counter when the lock has been released.
89 * It optionally update the <owner_xp> and <xlist> debug fields.
90 *******************************************************************************************
91 * @ lock_xp   : extended pointer on remote_queuelock.
92 ******************************************************************************************/
93void remote_queuelock_release( xptr_t lock_xp );
94
95
96#endif  /* _REMOTE_QUEUELOCK_H_ */
Note: See TracBrowser for help on using the repository browser.