Line data Source code
1 1 : /*
2 : * Copyright (c) 2018 Alexander Wachter
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @ingroup hwinfo_interface
10 : * @brief Main header file for hardware information (hwinfo) driver API.
11 : */
12 :
13 : #ifndef ZEPHYR_INCLUDE_DRIVERS_HWINFO_H_
14 : #define ZEPHYR_INCLUDE_DRIVERS_HWINFO_H_
15 :
16 : /**
17 : * @brief Interfaces allowing to obtain hardware information.
18 : * @defgroup hwinfo_interface Hardware Info
19 : * @since 1.14
20 : * @version 1.0.0
21 : * @ingroup io_interfaces
22 : * @{
23 : */
24 :
25 : #include <zephyr/types.h>
26 : #include <sys/types.h>
27 : #include <stddef.h>
28 : #include <errno.h>
29 : #include <zephyr/kernel.h>
30 :
31 : #ifdef __cplusplus
32 : extern "C" {
33 : #endif
34 :
35 : /**
36 : * @name Reset cause flags
37 : * @anchor reset_cause
38 : * @{
39 : */
40 : /** External pin */
41 1 : #define RESET_PIN BIT(0)
42 : /** Software reset */
43 1 : #define RESET_SOFTWARE BIT(1)
44 : /** Brownout (drop in voltage) */
45 1 : #define RESET_BROWNOUT BIT(2)
46 : /** Power-on reset (POR) */
47 1 : #define RESET_POR BIT(3)
48 : /** Watchdog timer expiration */
49 1 : #define RESET_WATCHDOG BIT(4)
50 : /** Debug event */
51 1 : #define RESET_DEBUG BIT(5)
52 : /** Security violation */
53 1 : #define RESET_SECURITY BIT(6)
54 : /** Waking up from low power mode */
55 1 : #define RESET_LOW_POWER_WAKE BIT(7)
56 : /** CPU lock-up detected */
57 1 : #define RESET_CPU_LOCKUP BIT(8)
58 : /** Parity error */
59 1 : #define RESET_PARITY BIT(9)
60 : /** PLL error */
61 1 : #define RESET_PLL BIT(10)
62 : /** Clock error */
63 1 : #define RESET_CLOCK BIT(11)
64 : /** Hardware reset */
65 1 : #define RESET_HARDWARE BIT(12)
66 : /** User reset */
67 1 : #define RESET_USER BIT(13)
68 : /** Temperature reset */
69 1 : #define RESET_TEMPERATURE BIT(14)
70 : /** Bootloader reset (entry / exit) */
71 1 : #define RESET_BOOTLOADER BIT(15)
72 : /** Flash ECC reset */
73 1 : #define RESET_FLASH BIT(16)
74 : /**
75 : * @}
76 : */
77 :
78 : /**
79 : * @brief Copy the device id to a buffer
80 : *
81 : * This routine copies "length" number of bytes of the device ID to the buffer.
82 : * If the device ID is smaller than length, the rest of the buffer is left unchanged.
83 : * The ID depends on the hardware and is not guaranteed unique.
84 : *
85 : * Drivers are responsible for ensuring that the ID data structure is a
86 : * sequence of bytes. The returned ID value is not supposed to be interpreted
87 : * based on vendor-specific assumptions of byte order. It should express the
88 : * identifier as a raw byte sequence, doing any endian conversion necessary so
89 : * that a hex representation of the bytes produces the intended serial number.
90 : *
91 : * @param buffer Buffer to write the ID to.
92 : * @param length Max length of the buffer.
93 : *
94 : * @retval size of the device ID copied.
95 : * @retval -ENOSYS if there is no implementation for the particular device.
96 : * @retval any negative value on driver specific errors.
97 : */
98 1 : __syscall ssize_t hwinfo_get_device_id(uint8_t *buffer, size_t length);
99 :
100 : ssize_t z_impl_hwinfo_get_device_id(uint8_t *buffer, size_t length);
101 :
102 : /**
103 : * @brief Copy the device EUI64 to a buffer
104 : *
105 : * This routine copies the device EUI64 (8 bytes) to the buffer.
106 : * The EUI64 depends on the hardware and is guaranteed unique.
107 : *
108 : * @param buffer Buffer of 8 bytes to write the ID to.
109 : *
110 : * @retval zero if successful.
111 : * @retval -ENOSYS if there is no implementation for the particular device.
112 : * @retval any negative value on driver specific errors.
113 : */
114 1 : __syscall int hwinfo_get_device_eui64(uint8_t *buffer);
115 :
116 : int z_impl_hwinfo_get_device_eui64(uint8_t *buffer);
117 :
118 : /**
119 : * @brief Retrieve cause of device reset.
120 : *
121 : * @param cause OR'd @ref reset_cause "reset cause" flags
122 : *
123 : * This routine retrieves the flags that indicate why the device was reset.
124 : *
125 : * On some platforms the reset cause flags accumulate between successive resets
126 : * and this routine may return multiple flags indicating all reset causes
127 : * since the device was powered on. If you need to retrieve the cause only for
128 : * the most recent reset call `hwinfo_clear_reset_cause` after calling this
129 : * routine to clear the hardware flags before the next reset event.
130 : *
131 : * Successive calls to this routine will return the same value, unless
132 : * `hwinfo_clear_reset_cause` has been called.
133 : *
134 : * @retval zero if successful.
135 : * @retval -ENOSYS if there is no implementation for the particular device.
136 : * @retval any negative value on driver specific errors.
137 : */
138 1 : __syscall int hwinfo_get_reset_cause(uint32_t *cause);
139 :
140 : int z_impl_hwinfo_get_reset_cause(uint32_t *cause);
141 :
142 : /**
143 : * @brief Clear cause of device reset.
144 : *
145 : * Clears reset cause flags.
146 : *
147 : * @retval zero if successful.
148 : * @retval -ENOSYS if there is no implementation for the particular device.
149 : * @retval any negative value on driver specific errors.
150 : */
151 1 : __syscall int hwinfo_clear_reset_cause(void);
152 :
153 : int z_impl_hwinfo_clear_reset_cause(void);
154 :
155 : /**
156 : * @brief Get supported reset cause flags
157 : *
158 : * @param supported OR'd @ref reset_cause "reset cause" flags that are supported
159 : *
160 : * Retrieves all `reset_cause` flags that are supported by this device.
161 : *
162 : * @retval zero if successful.
163 : * @retval -ENOSYS if there is no implementation for the particular device.
164 : * @retval any negative value on driver specific errors.
165 : */
166 1 : __syscall int hwinfo_get_supported_reset_cause(uint32_t *supported);
167 :
168 : int z_impl_hwinfo_get_supported_reset_cause(uint32_t *supported);
169 :
170 : /**
171 : * @}
172 : */
173 :
174 : #ifdef __cplusplus
175 : }
176 : #endif
177 :
178 : #include <zephyr/syscalls/hwinfo.h>
179 :
180 : #endif /* ZEPHYR_INCLUDE_DRIVERS_HWINFO_H_ */
|
