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_clear_bit(mem_addr_t addr, unsigned int bit)
250  * @brief Clear the designated bit from addr to 0
251  *
252  * This functions takes the designated bit starting from addr and sets it to 0.
253  *
254  * @param addr the memory address from where to look for the bit
255  * @param bit the designated bit to clear (from 0 to 31)
256  */
257 
258 /**
259  * @fn static inline int sys_test_bit(mem_addr_t addr, unsigned int bit)
260  * @brief Test the bit if it is set or not
261  *
262  * This functions takes the designated bit starting from addr and tests its
263  * current setting. It will return the current setting.
264  *
265  * @param addr the memory address from where to look for the bit
266  * @param bit the designated bit to test (from 0 to 31)
267  *
268  * @return 1 if it is set, 0 otherwise
269  */
270 
271 /**
272  * @fn static inline int sys_test_and_set_bit(mem_addr_t addr, unsigned int bit)
273  * @brief Test the bit and set it
274  *
275  * This functions takes the designated bit starting from addr, tests its
276  * current setting and sets it. It will return the previous setting.
277  *
278  * @param addr the memory address from where to look for the bit
279  * @param bit the designated bit to test and set (from 0 to 31)
280  *
281  * @return 1 if it was set, 0 otherwise
282  */
283 
284 /**
285  * @fn static inline int sys_test_and_clear_bit(mem_addr_t addr, unsigned int bit)
286  * @brief Test the bit and clear it
287  *
288  * This functions takes the designated bit starting from addr, test its
289  * current setting and clears it. It will return the previous setting.
290  *
291  * @param addr the memory address from where to look for the bit
292  * @param bit the designated bit to test and clear (from 0 to 31)
293  *
294  * @return 0 if it was clear, 1 otherwise
295  */
296 
297 /**
298  * @fn static inline void sys_bitfield_set_bit(mem_addr_t addr, unsigned int bit)
299  * @brief Set the designated bit from addr to 1
300  *
301  * This functions takes the designated bit starting from addr and sets it to 1.
302  *
303  * @param addr the memory address from where to look for the bit
304  * @param bit the designated bit to set (arbitrary)
305  */
306 
307 /**
308  * @fn static inline void sys_bitfield_clear_bit(mem_addr_t addr, unsigned int bit)
309  * @brief Clear the designated bit from addr to 0
310  *
311  * This functions takes the designated bit starting from addr and sets it to 0.
312  *
313  * @param addr the memory address from where to look for the bit
314  * @param bit the designated bit to clear (arbitrary)
315  */
316 
317 /**
318  * @fn static inline int sys_bitfield_test_bit(mem_addr_t addr, unsigned int bit)
319  * @brief Test the bit if it is set or not
320  *
321  * This functions takes the designated bit starting from addr and tests its
322  * current setting. It will return the current setting.
323  *
324  * @param addr the memory address from where to look for the bit
325  * @param bit the designated bit to test (arbitrary
326  *
327  * @return 1 if it is set, 0 otherwise
328  */
329 
330 /**
331  * @fn static inline int sys_bitfield_test_and_set_bit(mem_addr_t addr, unsigned int bit)
332  * @brief Test the bit and set it
333  *
334  * This functions takes the designated bit starting from addr, tests its
335  * current setting and sets it. It will return the previous setting.
336  *
337  * @param addr the memory address from where to look for the bit
338  * @param bit the designated bit to test and set (arbitrary)
339  *
340  * @return 1 if it was set, 0 otherwise
341  */
342 
343 /**
344  * @fn static inline int sys_bitfield_test_and_clear_bit(mem_addr_t addr, unsigned int bit)
345  * @brief Test the bit and clear it
346  *
347  * This functions takes the designated bit starting from addr, test its
348  * current setting and clears it. It will return the previous setting.
349  *
350  * @param addr the memory address from where to look for the bit
351  * @param bit the designated bit to test and clear (arbitrary)
352  *
353  * @return 0 if it was clear, 1 otherwise
354  */
355 
356 
357 #ifdef __cplusplus
358 }
359 #endif
360 
361 #endif /* ZEPHYR_INCLUDE_SYS_SYS_IO_H_ */
362