Line data Source code
1 1 : /*
2 : * Copyright (c) 2023 Sequans Communications
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @ingroup hwspinlock_interface
10 : * @brief Main header file for hardware spinlock driver API.
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_DRIVERS_HWSPINLOCK_H_
14 : #define ZEPHYR_INCLUDE_DRIVERS_HWSPINLOCK_H_
15 :
16 : /**
17 : * @brief Interfaces for hardware spinlocks.
18 : * @defgroup hwspinlock_interface Hardware Spinlock
19 : * @ingroup io_interfaces
20 : * @{
21 : */
22 :
23 : #include <errno.h>
24 : #include <zephyr/types.h>
25 : #include <zephyr/sys/util.h>
26 : #include <zephyr/device.h>
27 :
28 : #ifdef __cplusplus
29 : extern "C" {
30 : #endif
31 :
32 : /** @cond INTERNAL_HIDDEN */
33 :
34 : /**
35 : * @brief Callback API for trying to lock HW spinlock
36 : * @see hwspinlock_trylock().
37 : */
38 : typedef int (*hwspinlock_api_trylock)(const struct device *dev, uint32_t id);
39 :
40 : /**
41 : * @brief Callback API to lock HW spinlock
42 : * @see hwspinlock_lock().
43 : */
44 : typedef void (*hwspinlock_api_lock)(const struct device *dev, uint32_t id);
45 :
46 : /**
47 : * @brief Callback API to unlock HW spinlock
48 : * @see hwspinlock_unlock().
49 : */
50 : typedef void (*hwspinlock_api_unlock)(const struct device *dev, uint32_t id);
51 :
52 : /**
53 : * @brief Callback API to get HW spinlock max ID
54 : * @see hwspinlock_get_max_id().
55 : */
56 : typedef uint32_t (*hwspinlock_api_get_max_id)(const struct device *dev);
57 :
58 : __subsystem struct hwspinlock_driver_api {
59 : hwspinlock_api_trylock trylock;
60 : hwspinlock_api_lock lock;
61 : hwspinlock_api_unlock unlock;
62 : hwspinlock_api_get_max_id get_max_id;
63 : };
64 : /**
65 : * @endcond
66 : */
67 :
68 : /**
69 : * @brief Try to lock HW spinlock
70 : *
71 : * This function is used for try to lock specific HW spinlock. It should
72 : * be called before a critical section that we want to protect.
73 : *
74 : * @param dev HW spinlock device instance.
75 : * @param id Spinlock identifier.
76 : *
77 : * @retval 0 If successful.
78 : * @retval -errno In case of any failure.
79 : */
80 1 : __syscall int hwspinlock_trylock(const struct device *dev, uint32_t id);
81 :
82 : static inline int z_impl_hwspinlock_trylock(const struct device *dev, uint32_t id)
83 : {
84 : const struct hwspinlock_driver_api *api =
85 : (const struct hwspinlock_driver_api *)dev->api;
86 :
87 : if (api->trylock == NULL) {
88 : return -ENOSYS;
89 : }
90 :
91 : return api->trylock(dev, id);
92 : }
93 :
94 : /**
95 : * @brief Lock HW spinlock
96 : *
97 : * This function is used to lock specific HW spinlock. It should be
98 : * called before a critical section that we want to protect.
99 : *
100 : * @param dev HW spinlock device instance.
101 : * @param id Spinlock identifier.
102 : */
103 1 : __syscall void hwspinlock_lock(const struct device *dev, uint32_t id);
104 :
105 : static inline void z_impl_hwspinlock_lock(const struct device *dev, uint32_t id)
106 : {
107 : const struct hwspinlock_driver_api *api =
108 : (const struct hwspinlock_driver_api *)dev->api;
109 :
110 : if (api->lock != NULL) {
111 : api->lock(dev, id);
112 : }
113 : }
114 :
115 : /**
116 : * @brief Try to unlock HW spinlock
117 : *
118 : * This function is used for try to unlock specific HW spinlock. It should
119 : * be called after a critical section that we want to protect.
120 : *
121 : * @param dev HW spinlock device instance.
122 : * @param id Spinlock identifier.
123 : */
124 1 : __syscall void hwspinlock_unlock(const struct device *dev, uint32_t id);
125 :
126 : static inline void z_impl_hwspinlock_unlock(const struct device *dev, uint32_t id)
127 : {
128 : const struct hwspinlock_driver_api *api =
129 : (const struct hwspinlock_driver_api *)dev->api;
130 :
131 : if (api->unlock != NULL) {
132 : api->unlock(dev, id);
133 : }
134 : }
135 :
136 : /**
137 : * @brief Get HW spinlock max ID
138 : *
139 : * This function is used to get the HW spinlock maximum ID. It should
140 : * be called before attempting to lock/unlock a specific HW spinlock.
141 : *
142 : * @param dev HW spinlock device instance.
143 : *
144 : * @retval HW spinlock max ID.
145 : * @retval 0 if the function is not implemented by the driver.
146 : */
147 1 : __syscall uint32_t hwspinlock_get_max_id(const struct device *dev);
148 :
149 : static inline uint32_t z_impl_hwspinlock_get_max_id(const struct device *dev)
150 : {
151 : const struct hwspinlock_driver_api *api =
152 : (const struct hwspinlock_driver_api *)dev->api;
153 :
154 : if (api->get_max_id == NULL) {
155 : return 0;
156 : }
157 :
158 : return api->get_max_id(dev);
159 : }
160 :
161 : #ifdef __cplusplus
162 : }
163 : #endif
164 :
165 : /** @} */
166 :
167 : #include <zephyr/syscalls/hwspinlock.h>
168 :
169 : #endif /* ZEPHYR_INCLUDE_DRIVERS_HWSPINLOCK_H_ */
|
