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