1 /* Port and memory mapped registers I/O operations */
2 
3 /*
4  * Copyright (c) 2015 Intel Corporation.
5  *
6  * SPDX-License-Identifier: Apache-2.0
7  */
8 
9 #ifndef ZEPHYR_INCLUDE_SYS_SYS_IO_H_
10 #define ZEPHYR_INCLUDE_SYS_SYS_IO_H_
11 
12 #include <zephyr/types.h>
13 #include <stddef.h>
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
19 typedef uint32_t io_port_t;
20 typedef uintptr_t mm_reg_t;
21 typedef uintptr_t mem_addr_t;
22 
23 /* Port I/O functions */
24 
25 /**
26  * @fn static inline void sys_out8(uint8_t data, io_port_t port);
27  * @brief Output a byte to an I/O port
28  *
29  * This function writes a byte to the given port.
30  *
31  * @param data the byte to write
32  * @param port the port address where to write the byte
33  */
34 
35 /**
36  * @fn static inline uint8_t sys_in8(io_port_t port);
37  * @brief Input a byte from an I/O port
38  *
39  * This function reads a byte from the port.
40  *
41  * @param port the port address from where to read the byte
42  *
43  * @return the byte read
44  */
45 
46 /**
47  * @fn static inline void sys_out16(uint16_t data, io_port_t port);
48  * @brief Output a 16 bits to an I/O port
49  *
50  * This function writes a 16 bits to the given port.
51  *
52  * @param data the 16 bits to write
53  * @param port the port address where to write the 16 bits
54  */
55 
56 /**
57  * @fn static inline uint16_t sys_in16(io_port_t port);
58  * @brief Input 16 bits from an I/O port
59  *
60  * This function reads 16 bits from the port.
61  *
62  * @param port the port address from where to read the 16 bits
63  *
64  * @return the 16 bits read
65  */
66 
67 /**
68  * @fn static inline void sys_out32(uint32_t data, io_port_t port);
69  * @brief Output 32 bits to an I/O port
70  *
71  * This function writes 32 bits to the given port.
72  *
73  * @param data the 32 bits to write
74  * @param port the port address where to write the 32 bits
75  */
76 
77 /**
78  * @fn static inline uint32_t sys_in32(io_port_t port);
79  * @brief Input 32 bits from an I/O port
80  *
81  * This function reads 32 bits from the port.
82  *
83  * @param port the port address from where to read the 32 bits
84  *
85  * @return the 32 bits read
86  */
87 
88 /**
89  * @fn static inline void sys_io_set_bit(io_port_t port, unsigned int bit)
90  * @brief Set the designated bit from port to 1
91  *
92  * This functions takes the designated bit starting from port and sets it to 1.
93  *
94  * @param port the port address from where to look for the bit
95  * @param bit the designated bit to set (from 0 to n)
96  */
97 
98 /**
99  * @fn static inline void sys_io_clear_bit(io_port_t port, unsigned int bit)
100  * @brief Clear the designated bit from port to 0
101  *
102  * This functions takes the designated bit starting from port and sets it to 0.
103  *
104  * @param port the port address from where to look for the bit
105  * @param bit the designated bit to clear (from 0 to n)
106  */
107 
108 /**
109  * @fn static inline int sys_io_test_bit(io_port_t port, unsigned int bit)
110  * @brief Test the bit from port if it is set or not
111  *
112  * This functions takes the designated bit starting from port and tests its
113  * current setting. It will return the current setting.
114  *
115  * @param port the port address from where to look for the bit
116  * @param bit the designated bit to test (from 0 to n)
117  *
118  * @return 1 if it is set, 0 otherwise
119  */
120 
121 /**
122  * @fn static inline int sys_io_test_and_set_bit(io_port_t port, unsigned int bit)
123  * @brief Test the bit from port and set it
124  *
125  * This functions takes the designated bit starting from port, tests its
126  * current setting and sets it. It will return the previous setting.
127  *
128  * @param port the port address from where to look for the bit
129  * @param bit the designated bit to test and set (from 0 to n)
130  *
131  * @return 1 if it was set, 0 otherwise
132  */
133 
134 /**
135  * @fn static inline int sys_io_test_and_clear_bit(io_port_t port, unsigned int bit)
136  * @brief Test the bit from port and clear it
137  *
138  * This functions takes the designated bit starting from port, tests its
139  * current setting and clears it. It will return the previous setting.
140  *
141  * @param port the port address from where to look for the bit
142  * @param bit the designated bit to test and clear (from 0 to n)
143  *
144  * @return 0 if it was clear, 1 otherwise
145  */
146 
147 /* Memory mapped registers I/O functions */
148 
149 /**
150  * @fn static inline void sys_write8(uint8_t data, mm_reg_t addr);
151  * @brief Write a byte to a memory mapped register
152  *
153  * This function writes a byte to the given memory mapped register.
154  *
155  * @param data the byte to write
156  * @param addr the memory mapped register address where to write the byte
157  */
158 
159 /**
160  * @fn static inline uint8_t sys_read8(mm_reg_t addr);
161  * @brief Read a byte from a memory mapped register
162  *
163  * This function reads a byte from the given memory mapped register.
164  *
165  * @param addr the memory mapped register address from where to read the byte
166  *
167  * @return the byte read
168  */
169 
170 /**
171  * @fn static inline void sys_write16(uint16_t data, mm_reg_t addr);
172  * @brief Write 16 bits to a memory mapped register
173  *
174  * This function writes 16 bits to the given memory mapped register.
175  *
176  * @param data the 16 bits to write
177  * @param addr the memory mapped register address where to write the 16 bits
178  */
179 
180 /**
181  * @fn static inline uint16_t sys_read16(mm_reg_t addr);
182  * @brief Read 16 bits from a memory mapped register
183  *
184  * This function reads 16 bits from the given memory mapped register.
185  *
186  * @param addr the memory mapped register address from where to read
187  *        the 16 bits
188  *
189  * @return the 16 bits read
190  */
191 
192 /**
193  * @fn static inline void sys_write32(uint32_t data, mm_reg_t addr);
194  * @brief Write 32 bits to a memory mapped register
195  *
196  * This function writes 32 bits to the given memory mapped register.
197  *
198  * @param data the 32 bits to write
199  * @param addr the memory mapped register address where to write the 32 bits
200  */
201 
202 /**
203  * @fn static inline uint32_t sys_read32(mm_reg_t addr);
204  * @brief Read 32 bits from a memory mapped register
205  *
206  * This function reads 32 bits from the given memory mapped register.
207  *
208  * @param addr the memory mapped register address from where to read
209  *        the 32 bits
210  *
211  * @return the 32 bits read
212  */
213 
214 /**
215  * @fn static inline void sys_write64(uint64_t data, mm_reg_t addr);
216  * @brief Write 64 bits to a memory mapped register
217  *
218  * This function writes 64 bits to the given memory mapped register.
219  *
220  * @param data the 64 bits to write
221  * @param addr the memory mapped register address where to write the 64 bits
222  */
223 
224 /**
225  * @fn static inline uint64_t sys_read64(mm_reg_t addr);
226  * @brief Read 64 bits from a memory mapped register
227  *
228  * This function reads 64 bits from the given memory mapped register.
229  *
230  * @param addr the memory mapped register address from where to read
231  *        the 64 bits
232  *
233  * @return the 64 bits read
234  */
235 
236 /* Memory bits manipulation functions */
237 
238 /**
239  * @fn static inline void sys_set_bit(mem_addr_t addr, unsigned int bit)
240  * @brief Set the designated bit from addr to 1
241  *
242  * This functions takes the designated bit starting from addr and sets it to 1.
243  *
244  * @param addr the memory address from where to look for the bit
245  * @param bit the designated bit to set (from 0 to 31)
246  */
247 
248 /**
249  * @fn static inline void sys_set_bits(mem_addr_t addr, unsigned int mask)
250  * @brief Masking the designated bits from addr to 1
251  *
252  * This functions masking designated bits from addr to 1.
253  *
254  * @param addr the memory address from where to look for the bits
255  * @param mask the bit mask of a 32 bits data to set
256  */
257 
258 /**
259  * @fn static inline void sys_clear_bits(mem_addr_t addr, unsigned int mask)
260  * @brief Masking the designated bits from addr to 0
261  *
262  * This functions masking designated bits from addr to 0.
263  *
264  * @param addr the memory address from where to look for the bits
265  * @param mask the bit mask of a 32 bits data to set
266  */
267 
268 /**
269  * @fn static inline void sys_clear_bit(mem_addr_t addr, unsigned int bit)
270  * @brief Clear the designated bit from addr to 0
271  *
272  * This functions takes the designated bit starting from addr and sets it to 0.
273  *
274  * @param addr the memory address from where to look for the bit
275  * @param bit the designated bit to clear (from 0 to 31)
276  */
277 
278 /**
279  * @fn static inline int sys_test_bit(mem_addr_t addr, unsigned int bit)
280  * @brief Test the bit if it is set or not
281  *
282  * This functions takes the designated bit starting from addr and tests its
283  * current setting. It will return the current setting.
284  *
285  * @param addr the memory address from where to look for the bit
286  * @param bit the designated bit to test (from 0 to 31)
287  *
288  * @return 1 if it is set, 0 otherwise
289  */
290 
291 /**
292  * @fn static inline int sys_test_and_set_bit(mem_addr_t addr, unsigned int bit)
293  * @brief Test the bit and set it
294  *
295  * This functions takes the designated bit starting from addr, tests its
296  * current setting and sets it. It will return the previous setting.
297  *
298  * @param addr the memory address from where to look for the bit
299  * @param bit the designated bit to test and set (from 0 to 31)
300  *
301  * @return 1 if it was set, 0 otherwise
302  */
303 
304 /**
305  * @fn static inline int sys_test_and_clear_bit(mem_addr_t addr, unsigned int bit)
306  * @brief Test the bit and clear it
307  *
308  * This functions takes the designated bit starting from addr, test its
309  * current setting and clears it. It will return the previous setting.
310  *
311  * @param addr the memory address from where to look for the bit
312  * @param bit the designated bit to test and clear (from 0 to 31)
313  *
314  * @return 0 if it was clear, 1 otherwise
315  */
316 
317 /**
318  * @fn static inline void sys_bitfield_set_bit(mem_addr_t addr, unsigned int bit)
319  * @brief Set the designated bit from addr to 1
320  *
321  * This functions takes the designated bit starting from addr and sets it to 1.
322  *
323  * @param addr the memory address from where to look for the bit
324  * @param bit the designated bit to set (arbitrary)
325  */
326 
327 /**
328  * @fn static inline void sys_bitfield_clear_bit(mem_addr_t addr, unsigned int bit)
329  * @brief Clear the designated bit from addr to 0
330  *
331  * This functions takes the designated bit starting from addr and sets it to 0.
332  *
333  * @param addr the memory address from where to look for the bit
334  * @param bit the designated bit to clear (arbitrary)
335  */
336 
337 /**
338  * @fn static inline int sys_bitfield_test_bit(mem_addr_t addr, unsigned int bit)
339  * @brief Test the bit if it is set or not
340  *
341  * This functions takes the designated bit starting from addr and tests its
342  * current setting. It will return the current setting.
343  *
344  * @param addr the memory address from where to look for the bit
345  * @param bit the designated bit to test (arbitrary
346  *
347  * @return 1 if it is set, 0 otherwise
348  */
349 
350 /**
351  * @fn static inline int sys_bitfield_test_and_set_bit(mem_addr_t addr, unsigned int bit)
352  * @brief Test the bit and set it
353  *
354  * This functions takes the designated bit starting from addr, tests its
355  * current setting and sets it. It will return the previous setting.
356  *
357  * @param addr the memory address from where to look for the bit
358  * @param bit the designated bit to test and set (arbitrary)
359  *
360  * @return 1 if it was set, 0 otherwise
361  */
362 
363 /**
364  * @fn static inline int sys_bitfield_test_and_clear_bit(mem_addr_t addr, unsigned int bit)
365  * @brief Test the bit and clear it
366  *
367  * This functions takes the designated bit starting from addr, test its
368  * current setting and clears it. It will return the previous setting.
369  *
370  * @param addr the memory address from where to look for the bit
371  * @param bit the designated bit to test and clear (arbitrary)
372  *
373  * @return 0 if it was clear, 1 otherwise
374  */
375 
376 
377 #ifdef __cplusplus
378 }
379 #endif
380 
381 #endif /* ZEPHYR_INCLUDE_SYS_SYS_IO_H_ */
382