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

Last change on this file since 623 was 623, checked in by alain, 3 years ago

Introduce three new types of vsegs (KCODE,KDATA,KDEV)
to map the kernel vsegs in the process VSL and GPT.
This now used by both the TSAR and the I86 architectures.

File size: 4.9 KB
RevLine 
[563]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
[623]36 * be used to execute very short actions, such as accessing basic allocators, or higher
37 * level synchronisation objects (barriers, queuelocks, or rwlocks).
38 * WARNING: a thread cannot yield when it is owning a busylock.
[563]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.