1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
/*
* Copyright (c) 2017-2019 Richard Braun.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*
* Semaphores are resource-counting sleeping synchronization objects.
* They are used to synchronize access to resources and signal events.
*
* The main operations supported by semaphores are waiting and signalling.
* A semaphore is implemented as a counter with an initial value. Waiting
* on a semaphore means decrementing that counter, whereas signalling
* means incrementing it. Waiting can only succeed if the semaphore value
* is strictly greater than 0.
*
* The use of semaphores is generally discouraged. Mutexes are recommended
* to implement preemptible critical sections, and spinlocks combined with
* calls to thread_sleep() and thread_wakeup() are recommended for
* non-preemptible critical sections. The reason is that a semaphore
* internally already uses a spinlock, but that internal lock may not be
* used to serialize access to anything else. This means that the only case
* where a semaphore may be an efficient synchronization mechanism is
* real-time signalling, e.g. an interrupt handler signalling a thread.
* Here, "real-time" means that there is a guarantee that the thread has
* always consumed the data produced by the interrupt handler before the
* latter runs again.
*
* Since the kernel is an incomplete program without applications, it is
* impossible to perform an analysis providing the real-time guarantee.
* As a result, semaphores may only be used by application code.
*/
#ifndef KERN_SEMAPHORE_H
#define KERN_SEMAPHORE_H
#include <assert.h>
#include <errno.h>
#include <stdint.h>
#include <kern/semaphore_i.h>
struct semaphore;
/*
* Initialize a semaphore.
*/
void semaphore_init(struct semaphore *semaphore, uint16_t value,
uint16_t max_value);
/*
* Attempt to decrement a semaphore.
*
* This function may not sleep.
*
* Return 0 on success, EAGAIN if the semaphore could not be decremented.
*/
int semaphore_trywait(struct semaphore *semaphore);
/*
* Wait on a semaphore.
*
* If the semaphore value cannot be decremented, the calling thread sleeps
* until the semaphore value is incremented.
*/
void semaphore_wait(struct semaphore *semaphore);
/*
* Wait on a semaphore, with a time boundary.
*
* The time boundary is an absolute time in ticks.
*
* If successful, the semaphore is decremented, otherwise an error is returned.
*/
int semaphore_timedwait(struct semaphore *semaphore, uint64_t ticks);
/*
* Signal a semaphore.
*
* This function attempts to increment the semaphore value. If successful, and
* if one or more threads are waiting on the semaphore, one of them is awoken.
*
* A semaphore may safely be signalled from interrupt context.
*
* If successful, the semaphore is incremented. Otherwise, if the semaphore
* value is already at its maximum before calling this function, EOVERFLOW
* is returned.
*/
int semaphore_post(struct semaphore *semaphore);
#endif /* KERN_SEMAPHORE_H */
|
