source: trunk/kernel/libk/busylock.h @ 583

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

Complete restructuration of kernel spinlocks.

File size: 4.9 KB
Line 
1/*
2 * busylock.h: local kernel busy-waiting lock 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 _BUSYLOCK_H_
25#define _BUSYLOCK_H_
26
27#include <kernel_config.h>
28#include <hal_kernel_types.h>
29#include <hal_shared_types.h>
30#include <xlist.h>
31
32/*******************************************************************************************
33 * This synchronisation object sequencializes all concurrent read or write accesses to
34 * a shared object located in a given cluster, made by thread(s) running in same cluster.
35 * It uses a busy waiting policy when the lock is taken by another thread, and should
36 * be used to execute very short actions, such as basic allocators, or to protect
37 * higher level synchronisation objects, such as queuelock or rwlock.
38 * WARNING: a thread cannot yield when it is owning a busylock (local or remote).
39 *
40 * - To acquire the lock, we use a ticket policy to avoid starvation: the calling thread
41 *   makes an atomic increment on a "ticket" allocator, and keep polling the "current"
42 *   value  until current == ticket.
43 *
44 * - To release the lock, the owner thread increments the "current" value,
45 *   decrements its busylocks counter.
46 *
47 * - When a thread takes a busylock, it enters a critical section: the busylock_acquire()
48 *   function disables the IRQs, takes the lock, increments the thread busylocks counter,
49 *   and save the SR in lock descriptor and returns.
50 *
51 * - The busylock_release() function releases the lock, decrements the thread busylock
52 *   counter, restores the SR to exit the critical section, and returns
53 *
54 * - If a thread owning a busylock (local or remote) tries to deschedule, the scheduler
55 *   signals a kernel panic.
56 ******************************************************************************************/
57
58/*******************************************************************************************
59 * This structure defines a busylock.
60 * The <type> and <xlist> fields are used for debug.
61 * The type defines the lock usage as detailed in the kernel_config.h file.
62******************************************************************************************/
63
64typedef struct busylock_s
65{
66        uint32_t            ticket;      /*! next free ticket index                           */
67    volatile uint32_t   current;     /*! current owner index                              */
68    uint32_t            type;        /*! lock type for debug                              */
69    reg_t               save_sr;     /*! SR value                                         */
70
71#if DEBUG_BUSYLOCK
72    xlist_entry_t       xlist;       /*! member of list of locks taken by same thread     */
73#endif
74
75}
76busylock_t;
77
78/*******************************************************************************************
79 * This function initializes a busylock.
80 *******************************************************************************************
81 * @ lock    : local pointer on busylock.
82 * @ type    : lock  type for debug.
83 ******************************************************************************************/
84void busylock_init( busylock_t * lock,
85                    uint32_t    type );
86
87/*******************************************************************************************
88 * This blocking function uses a busy waiting strategy to acquire a busylock.
89 * It makes an atomic increment on the "ticket" field to get a ticket value and increment
90 * the ticket allocator.
91 * Then it polls the "current" field until (current == ticket), and returns.
92 *******************************************************************************************
93 * @ lock    : local pointer on busylock.
94 ******************************************************************************************/
95void busylock_acquire( busylock_t * lock );
96
97/*******************************************************************************************
98 * This function releases a busylock by incrementing the "current" field.
99 *******************************************************************************************
100 * @ lock    : local pointer on busylock.
101 ******************************************************************************************/
102void busylock_release( busylock_t * lock );
103
104#endif  /* _BUSYLOCK_H_ */
Note: See TracBrowser for help on using the repository browser.