1 /*
2 * External connector (extcon) class driver
3 *
4 * Copyright (C) 2012 Samsung Electronics
5 * Author: Donggeun Kim <dg77.kim@samsung.com>
6 * Author: MyungJoo Ham <myungjoo.ham@samsung.com>
7 *
8 * based on switch class driver
9 * Copyright (C) 2008 Google, Inc.
10 * Author: Mike Lockwood <lockwood@android.com>
11 *
12 * This software is licensed under the terms of the GNU General Public
13 * License version 2, as published by the Free Software Foundation, and
14 * may be copied, distributed, and modified under those terms.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
20 *
21 */
22
23 #ifndef __LINUX_EXTCON_H__
24 #define __LINUX_EXTCON_H__
25
26 #include <linux/device.h>
27 #include <linux/notifier.h>
28 #include <linux/sysfs.h>
29
30 #define SUPPORTED_CABLE_MAX 32
31 #define CABLE_NAME_MAX 30
32
33 /*
34 * The standard cable name is to help support general notifier
35 * and notifiee device drivers to share the common names.
36 * Please use standard cable names unless your notifier device has
37 * a very unique and abnormal cable or
38 * the cable type is supposed to be used with only one unique
39 * pair of notifier/notifiee devices.
40 *
41 * Please add any other "standard" cables used with extcon dev.
42 *
43 * You may add a dot and number to specify version or specification
44 * of the specific cable if it is required. (e.g., "Fast-charger.18"
45 * and "Fast-charger.10" for 1.8A and 1.0A chargers)
46 * However, the notifiee and notifier should be able to handle such
47 * string and if the notifiee can negotiate the protocol or identify,
48 * you don't need such convention. This convention is helpful when
49 * notifier can distinguish but notifiee cannot.
50 */
51 enum extcon_cable_name {
52 EXTCON_USB = 0,
53 EXTCON_USB_HOST,
54 EXTCON_TA, /* Travel Adaptor */
55 EXTCON_FAST_CHARGER,
56 EXTCON_SLOW_CHARGER,
57 EXTCON_CHARGE_DOWNSTREAM, /* Charging an external device */
58 EXTCON_HDMI,
59 EXTCON_MHL,
60 EXTCON_DVI,
61 EXTCON_VGA,
62 EXTCON_DOCK,
63 EXTCON_LINE_IN,
64 EXTCON_LINE_OUT,
65 EXTCON_MIC_IN,
66 EXTCON_HEADPHONE_OUT,
67 EXTCON_SPDIF_IN,
68 EXTCON_SPDIF_OUT,
69 EXTCON_VIDEO_IN,
70 EXTCON_VIDEO_OUT,
71 EXTCON_MECHANICAL,
72 };
73 extern const char extcon_cable_name[][CABLE_NAME_MAX + 1];
74
75 struct extcon_cable;
76
77 /**
78 * struct extcon_dev - An extcon device represents one external connector.
79 * @name: The name of this extcon device. Parent device name is used
80 * if NULL.
81 * @supported_cable: Array of supported cable names ending with NULL.
82 * If supported_cable is NULL, cable name related APIs
83 * are disabled.
84 * @mutually_exclusive: Array of mutually exclusive set of cables that cannot
85 * be attached simultaneously. The array should be
86 * ending with NULL or be NULL (no mutually exclusive
87 * cables). For example, if it is { 0x7, 0x30, 0}, then,
88 * {0, 1}, {0, 1, 2}, {0, 2}, {1, 2}, or {4, 5} cannot
89 * be attached simulataneously. {0x7, 0} is equivalent to
90 * {0x3, 0x6, 0x5, 0}. If it is {0xFFFFFFFF, 0}, there
91 * can be no simultaneous connections.
92 * @print_name: An optional callback to override the method to print the
93 * name of the extcon device.
94 * @print_state: An optional callback to override the method to print the
95 * status of the extcon device.
96 * @dev: Device of this extcon. Do not provide at register-time.
97 * @state: Attach/detach state of this extcon. Do not provide at
98 * register-time
99 * @nh: Notifier for the state change events from this extcon
100 * @entry: To support list of extcon devices so that users can search
101 * for extcon devices based on the extcon name.
102 * @lock:
103 * @max_supported: Internal value to store the number of cables.
104 * @extcon_dev_type: Device_type struct to provide attribute_groups
105 * customized for each extcon device.
106 * @cables: Sysfs subdirectories. Each represents one cable.
107 *
108 * In most cases, users only need to provide "User initializing data" of
109 * this struct when registering an extcon. In some exceptional cases,
110 * optional callbacks may be needed. However, the values in "internal data"
111 * are overwritten by register function.
112 */
113 struct extcon_dev {
114 /* --- Optional user initializing data --- */
115 const char *name;
116 const char **supported_cable;
117 const u32 *mutually_exclusive;
118
119 /* --- Optional callbacks to override class functions --- */
120 ssize_t (*print_name)(struct extcon_dev *edev, char *buf);
121 ssize_t (*print_state)(struct extcon_dev *edev, char *buf);
122
123 /* --- Internal data. Please do not set. --- */
124 struct device *dev;
125 u32 state;
126 struct raw_notifier_head nh;
127 struct list_head entry;
128 spinlock_t lock; /* could be called by irq handler */
129 int max_supported;
130
131 /* /sys/class/extcon/.../cable.n/... */
132 struct device_type extcon_dev_type;
133 struct extcon_cable *cables;
134 /* /sys/class/extcon/.../mutually_exclusive/... */
135 struct attribute_group attr_g_muex;
136 struct attribute **attrs_muex;
137 struct device_attribute *d_attrs_muex;
138 };
139
140 /**
141 * struct extcon_cable - An internal data for each cable of extcon device.
142 * @edev: The extcon device
143 * @cable_index: Index of this cable in the edev
144 * @attr_g: Attribute group for the cable
145 * @attr_name: "name" sysfs entry
146 * @attr_state: "state" sysfs entry
147 * @attrs: Array pointing to attr_name and attr_state for attr_g
148 */
149 struct extcon_cable {
150 struct extcon_dev *edev;
151 int cable_index;
152
153 struct attribute_group attr_g;
154 struct device_attribute attr_name;
155 struct device_attribute attr_state;
156
157 struct attribute *attrs[3]; /* to be fed to attr_g.attrs */
158 };
159
160 /**
161 * struct extcon_specific_cable_nb - An internal data for
162 * extcon_register_interest().
163 * @internal_nb: a notifier block bridging extcon notifier and cable notifier.
164 * @user_nb: user provided notifier block for events from a specific cable.
165 * @cable_index: the target cable.
166 * @edev: the target extcon device.
167 * @previous_value: the saved previous event value.
168 */
169 struct extcon_specific_cable_nb {
170 struct notifier_block internal_nb;
171 struct notifier_block *user_nb;
172 int cable_index;
173 struct extcon_dev *edev;
174 unsigned long previous_value;
175 };
176
177 #if IS_ENABLED(CONFIG_EXTCON)
178
179 /*
180 * Following APIs are for notifiers or configurations.
181 * Notifiers are the external port and connection devices.
182 */
183 extern int extcon_dev_register(struct extcon_dev *edev, struct device *dev);
184 extern void extcon_dev_unregister(struct extcon_dev *edev);
185 extern struct extcon_dev *extcon_get_extcon_dev(const char *extcon_name);
186
187 /*
188 * get/set/update_state access the 32b encoded state value, which represents
189 * states of all possible cables of the multistate port. For example, if one
190 * calls extcon_set_state(edev, 0x7), it may mean that all the three cables
191 * are attached to the port.
192 */
extcon_get_state(struct extcon_dev * edev)193 static inline u32 extcon_get_state(struct extcon_dev *edev)
194 {
195 return edev->state;
196 }
197
198 extern int extcon_set_state(struct extcon_dev *edev, u32 state);
199 extern int extcon_update_state(struct extcon_dev *edev, u32 mask, u32 state);
200
201 /*
202 * get/set_cable_state access each bit of the 32b encoded state value.
203 * They are used to access the status of each cable based on the cable_name
204 * or cable_index, which is retrieved by extcon_find_cable_index
205 */
206 extern int extcon_find_cable_index(struct extcon_dev *sdev,
207 const char *cable_name);
208 extern int extcon_get_cable_state_(struct extcon_dev *edev, int cable_index);
209 extern int extcon_set_cable_state_(struct extcon_dev *edev, int cable_index,
210 bool cable_state);
211
212 extern int extcon_get_cable_state(struct extcon_dev *edev,
213 const char *cable_name);
214 extern int extcon_set_cable_state(struct extcon_dev *edev,
215 const char *cable_name, bool cable_state);
216
217 /*
218 * Following APIs are for notifiees (those who want to be notified)
219 * to register a callback for events from a specific cable of the extcon.
220 * Notifiees are the connected device drivers wanting to get notified by
221 * a specific external port of a connection device.
222 */
223 extern int extcon_register_interest(struct extcon_specific_cable_nb *obj,
224 const char *extcon_name,
225 const char *cable_name,
226 struct notifier_block *nb);
227 extern int extcon_unregister_interest(struct extcon_specific_cable_nb *nb);
228
229 /*
230 * Following APIs are to monitor every action of a notifier.
231 * Registrar gets notified for every external port of a connection device.
232 * Probably this could be used to debug an action of notifier; however,
233 * we do not recommend to use this for normal 'notifiee' device drivers who
234 * want to be notified by a specific external port of the notifier.
235 */
236 extern int extcon_register_notifier(struct extcon_dev *edev,
237 struct notifier_block *nb);
238 extern int extcon_unregister_notifier(struct extcon_dev *edev,
239 struct notifier_block *nb);
240 #else /* CONFIG_EXTCON */
extcon_dev_register(struct extcon_dev * edev,struct device * dev)241 static inline int extcon_dev_register(struct extcon_dev *edev,
242 struct device *dev)
243 {
244 return 0;
245 }
246
extcon_dev_unregister(struct extcon_dev * edev)247 static inline void extcon_dev_unregister(struct extcon_dev *edev) { }
248
extcon_get_state(struct extcon_dev * edev)249 static inline u32 extcon_get_state(struct extcon_dev *edev)
250 {
251 return 0;
252 }
253
extcon_set_state(struct extcon_dev * edev,u32 state)254 static inline int extcon_set_state(struct extcon_dev *edev, u32 state)
255 {
256 return 0;
257 }
258
extcon_update_state(struct extcon_dev * edev,u32 mask,u32 state)259 static inline int extcon_update_state(struct extcon_dev *edev, u32 mask,
260 u32 state)
261 {
262 return 0;
263 }
264
extcon_find_cable_index(struct extcon_dev * edev,const char * cable_name)265 static inline int extcon_find_cable_index(struct extcon_dev *edev,
266 const char *cable_name)
267 {
268 return 0;
269 }
270
extcon_get_cable_state_(struct extcon_dev * edev,int cable_index)271 static inline int extcon_get_cable_state_(struct extcon_dev *edev,
272 int cable_index)
273 {
274 return 0;
275 }
276
extcon_set_cable_state_(struct extcon_dev * edev,int cable_index,bool cable_state)277 static inline int extcon_set_cable_state_(struct extcon_dev *edev,
278 int cable_index, bool cable_state)
279 {
280 return 0;
281 }
282
extcon_get_cable_state(struct extcon_dev * edev,const char * cable_name)283 static inline int extcon_get_cable_state(struct extcon_dev *edev,
284 const char *cable_name)
285 {
286 return 0;
287 }
288
extcon_set_cable_state(struct extcon_dev * edev,const char * cable_name,int state)289 static inline int extcon_set_cable_state(struct extcon_dev *edev,
290 const char *cable_name, int state)
291 {
292 return 0;
293 }
294
extcon_get_extcon_dev(const char * extcon_name)295 static inline struct extcon_dev *extcon_get_extcon_dev(const char *extcon_name)
296 {
297 return NULL;
298 }
299
extcon_register_notifier(struct extcon_dev * edev,struct notifier_block * nb)300 static inline int extcon_register_notifier(struct extcon_dev *edev,
301 struct notifier_block *nb)
302 {
303 return 0;
304 }
305
extcon_unregister_notifier(struct extcon_dev * edev,struct notifier_block * nb)306 static inline int extcon_unregister_notifier(struct extcon_dev *edev,
307 struct notifier_block *nb)
308 {
309 return 0;
310 }
311
extcon_register_interest(struct extcon_specific_cable_nb * obj,const char * extcon_name,const char * cable_name,struct notifier_block * nb)312 static inline int extcon_register_interest(struct extcon_specific_cable_nb *obj,
313 const char *extcon_name,
314 const char *cable_name,
315 struct notifier_block *nb)
316 {
317 return 0;
318 }
319
extcon_unregister_interest(struct extcon_specific_cable_nb * obj)320 static inline int extcon_unregister_interest(struct extcon_specific_cable_nb
321 *obj)
322 {
323 return 0;
324 }
325 #endif /* CONFIG_EXTCON */
326 #endif /* __LINUX_EXTCON_H__ */
327