1 /*
2 * Copyright 2023 Cirrus Logic, Inc.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #ifndef ZEPHYR_INCLUDE_DRIVERS_CHARGER_H_
8 #define ZEPHYR_INCLUDE_DRIVERS_CHARGER_H_
9
10 /**
11 * @brief Charger Interface
12 * @defgroup charger_interface Charger Interface
13 * @ingroup io_interfaces
14 * @{
15 */
16
17 #include <stdbool.h>
18 #include <stddef.h>
19 #include <stdint.h>
20
21 #include <zephyr/device.h>
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif /* __cplusplus */
26
27 /**
28 * @brief Runtime Dynamic Battery Parameters
29 */
30 enum charger_property {
31 /** Indicates if external supply is present for the charger. */
32 /** Value should be of type enum charger_online */
33 CHARGER_PROP_ONLINE = 0,
34 /** Reports whether or not a battery is present. */
35 /** Value should be of type bool*/
36 CHARGER_PROP_PRESENT,
37 /** Represents the charging status of the charger. */
38 /** Value should be of type enum charger_status */
39 CHARGER_PROP_STATUS,
40 /** Reserved to demark end of common charger properties */
41 CHARGER_PROP_COMMON_COUNT,
42 /**
43 * Reserved to demark downstream custom properties - use this value as the actual value may
44 * change over future versions of this API
45 */
46 CHARGER_PROP_CUSTOM_BEGIN = CHARGER_PROP_COMMON_COUNT + 1,
47 /** Reserved to demark end of valid enum properties */
48 CHARGER_PROP_MAX = UINT16_MAX,
49 };
50
51 /**
52 * @typedef charger_prop_t
53 * @brief A charger property's identifier
54 *
55 * See charger_property for a list of identifiers
56 */
57 typedef uint16_t charger_prop_t;
58
59 /**
60 * @brief External supply states
61 */
62 enum charger_online {
63 /** External supply not present */
64 CHARGER_ONLINE_OFFLINE = 0,
65 /** External supply is present and of fixed output */
66 CHARGER_ONLINE_FIXED,
67 /** External supply is present and of programmable output*/
68 CHARGER_ONLINE_PROGRAMMABLE,
69 };
70
71 /**
72 * @brief Charging states
73 */
74 enum charger_status {
75 /** Charging device state is unknown */
76 CHARGER_STATUS_UNKNOWN = 0,
77 /** Charging device is charging a battery */
78 CHARGER_STATUS_CHARGING,
79 /** Charging device is not able to charge a battery */
80 CHARGER_STATUS_DISCHARGING,
81 /** Charging device is not charging a battery */
82 CHARGER_STATUS_NOT_CHARGING,
83 /** The battery is full and the charging device will not attempt charging */
84 CHARGER_STATUS_FULL,
85 };
86
87 /**
88 * @brief container for a charger_property value
89 *
90 */
91 union charger_propval {
92 /* Fields have the format: */
93 /* CHARGER_PROPERTY_FIELD */
94 /* type property_field; */
95
96 /** CHARGER_PROP_ONLINE */
97 enum charger_online online;
98 /** CHARGER_PROP_PRESENT */
99 bool present;
100 /** CHARGER_PROP_STATUS */
101 enum charger_status status;
102 };
103
104 /**
105 * @typedef charger_get_property_t
106 * @brief Callback API for getting a charger property.
107 *
108 * See charger_get_property() for argument description
109 */
110 typedef int (*charger_get_property_t)(const struct device *dev, const charger_prop_t prop,
111 union charger_propval *val);
112
113 /**
114 * @typedef charger_set_property_t
115 * @brief Callback API for setting a charger property.
116 *
117 * See charger_set_property() for argument description
118 */
119 typedef int (*charger_set_property_t)(const struct device *dev, const charger_prop_t prop,
120 const union charger_propval *val);
121
122 /**
123 * @brief Charging device API
124 *
125 * Caching is entirely on the onus of the client
126 */
127 __subsystem struct charger_driver_api {
128 charger_get_property_t get_property;
129 charger_set_property_t set_property;
130 };
131
132 /**
133 * @brief Fetch a battery charger property
134 *
135 * @param dev Pointer to the battery charger device
136 * @param prop Charger property to get
137 * @param val Pointer to charger_propval union
138 *
139 * @retval 0 if successful
140 * @retval < 0 if getting property failed
141 */
142 __syscall int charger_get_prop(const struct device *dev, const charger_prop_t prop,
143 union charger_propval *val);
144
z_impl_charger_get_prop(const struct device * dev,const charger_prop_t prop,union charger_propval * val)145 static inline int z_impl_charger_get_prop(const struct device *dev, const charger_prop_t prop,
146 union charger_propval *val)
147 {
148 const struct charger_driver_api *api = (const struct charger_driver_api *)dev->api;
149
150 return api->get_property(dev, prop, val);
151 }
152
153 /**
154 * @brief Set a battery charger property
155 *
156 * @param dev Pointer to the battery charger device
157 * @param prop Charger property to set
158 * @param val Pointer to charger_propval union
159 *
160 * @retval 0 if successful
161 * @retval < 0 if setting property failed
162 */
163 __syscall int charger_set_prop(const struct device *dev, const charger_prop_t prop,
164 const union charger_propval *val);
165
z_impl_charger_set_prop(const struct device * dev,const charger_prop_t prop,const union charger_propval * val)166 static inline int z_impl_charger_set_prop(const struct device *dev, const charger_prop_t prop,
167 const union charger_propval *val)
168 {
169 const struct charger_driver_api *api = (const struct charger_driver_api *)dev->api;
170
171 return api->set_property(dev, prop, val);
172 }
173
174 /**
175 * @}
176 */
177
178 #ifdef __cplusplus
179 }
180 #endif /* __cplusplus */
181
182 #include <syscalls/charger.h>
183
184 #endif /* ZEPHYR_INCLUDE_DRIVERS_CHARGER_H_ */
185
