1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 /*
3  * Copyright (c) 2004 Evgeniy Polyakov <zbr@ioremap.net>
4  */
5 
6 #ifndef __LINUX_W1_H
7 #define __LINUX_W1_H
8 
9 #include <linux/device.h>
10 
11 /**
12  * struct w1_reg_num - broken out slave device id
13  *
14  * @family: identifies the type of device
15  * @id: along with family is the unique device id
16  * @crc: checksum of the other bytes
17  */
18 struct w1_reg_num {
19 #if defined(__LITTLE_ENDIAN_BITFIELD)
20 	__u64	family:8,
21 		id:48,
22 		crc:8;
23 #elif defined(__BIG_ENDIAN_BITFIELD)
24 	__u64	crc:8,
25 		id:48,
26 		family:8;
27 #else
28 #error "Please fix <asm/byteorder.h>"
29 #endif
30 };
31 
32 #ifdef __KERNEL__
33 
34 #define W1_MAXNAMELEN		32
35 
36 #define W1_SEARCH		0xF0
37 #define W1_ALARM_SEARCH		0xEC
38 #define W1_CONVERT_TEMP		0x44
39 #define W1_SKIP_ROM		0xCC
40 #define W1_COPY_SCRATCHPAD	0x48
41 #define W1_WRITE_SCRATCHPAD	0x4E
42 #define W1_READ_SCRATCHPAD	0xBE
43 #define W1_READ_ROM		0x33
44 #define W1_READ_PSUPPLY		0xB4
45 #define W1_MATCH_ROM		0x55
46 #define W1_RESUME_CMD		0xA5
47 
48 /**
49  * struct w1_slave - holds a single slave device on the bus
50  *
51  * @owner: Points to the one wire "wire" kernel module.
52  * @name: Device id is ascii.
53  * @w1_slave_entry: data for the linked list
54  * @reg_num: the slave id in binary
55  * @refcnt: reference count, delete when 0
56  * @flags: bit flags for W1_SLAVE_ACTIVE W1_SLAVE_DETACH
57  * @ttl: decrement per search this slave isn't found, deatch at 0
58  * @master: bus which this slave is on
59  * @family: module for device family type
60  * @family_data: pointer for use by the family module
61  * @dev: kernel device identifier
62  * @hwmon: pointer to hwmon device
63  *
64  */
65 struct w1_slave {
66 	struct module		*owner;
67 	unsigned char		name[W1_MAXNAMELEN];
68 	struct list_head	w1_slave_entry;
69 	struct w1_reg_num	reg_num;
70 	atomic_t		refcnt;
71 	int			ttl;
72 	unsigned long		flags;
73 
74 	struct w1_master	*master;
75 	struct w1_family	*family;
76 	void			*family_data;
77 	struct device		dev;
78 	struct device		*hwmon;
79 };
80 
81 typedef void (*w1_slave_found_callback)(struct w1_master *, u64);
82 
83 /**
84  * struct w1_bus_master - operations available on a bus master
85  *
86  * @data: the first parameter in all the functions below
87  *
88  * @read_bit: Sample the line level @return the level read (0 or 1)
89  *
90  * @write_bit: Sets the line level
91  *
92  * @touch_bit: the lowest-level function for devices that really support the
93  * 1-wire protocol.
94  * touch_bit(0) = write-0 cycle
95  * touch_bit(1) = write-1 / read cycle
96  * @return the bit read (0 or 1)
97  *
98  * @read_byte: Reads a bytes. Same as 8 touch_bit(1) calls.
99  * @return the byte read
100  *
101  * @write_byte: Writes a byte. Same as 8 touch_bit(x) calls.
102  *
103  * @read_block: Same as a series of read_byte() calls
104  * @return the number of bytes read
105  *
106  * @write_block: Same as a series of write_byte() calls
107  *
108  * @triplet: Combines two reads and a smart write for ROM searches
109  * @return bit0=Id bit1=comp_id bit2=dir_taken
110  *
111  * @reset_bus: long write-0 with a read for the presence pulse detection
112  * @return -1=Error, 0=Device present, 1=No device present
113  *
114  * @set_pullup: Put out a strong pull-up pulse of the specified duration.
115  * @return -1=Error, 0=completed
116  *
117  * @search: Really nice hardware can handles the different types of ROM search
118  * w1_master* is passed to the slave found callback.
119  * u8 is search_type, W1_SEARCH or W1_ALARM_SEARCH
120  *
121  * @dev_id: Optional device id string, which w1 slaves could use for
122  * creating names, which then give a connection to the w1 master
123  *
124  * Note: read_bit and write_bit are very low level functions and should only
125  * be used with hardware that doesn't really support 1-wire operations,
126  * like a parallel/serial port.
127  * Either define read_bit and write_bit OR define, at minimum, touch_bit and
128  * reset_bus.
129  *
130  */
131 struct w1_bus_master {
132 	void		*data;
133 
134 	u8		(*read_bit)(void *);
135 
136 	void		(*write_bit)(void *, u8);
137 
138 	u8		(*touch_bit)(void *, u8);
139 
140 	u8		(*read_byte)(void *);
141 
142 	void		(*write_byte)(void *, u8);
143 
144 	u8		(*read_block)(void *, u8 *, int);
145 
146 	void		(*write_block)(void *, const u8 *, int);
147 
148 	u8		(*triplet)(void *, u8);
149 
150 	u8		(*reset_bus)(void *);
151 
152 	u8		(*set_pullup)(void *, int);
153 
154 	void		(*search)(void *, struct w1_master *,
155 		u8, w1_slave_found_callback);
156 
157 	char		*dev_id;
158 };
159 
160 /**
161  * enum w1_master_flags - bitfields used in w1_master.flags
162  * @W1_ABORT_SEARCH: abort searching early on shutdown
163  * @W1_WARN_MAX_COUNT: limit warning when the maximum count is reached
164  */
165 enum w1_master_flags {
166 	W1_ABORT_SEARCH = 0,
167 	W1_WARN_MAX_COUNT = 1,
168 };
169 
170 /**
171  * struct w1_master - one per bus master
172  * @w1_master_entry:	master linked list
173  * @owner:		module owner
174  * @name:		dynamically allocate bus name
175  * @list_mutex:		protect slist and async_list
176  * @slist:		linked list of slaves
177  * @async_list:		linked list of netlink commands to execute
178  * @max_slave_count:	maximum number of slaves to search for at a time
179  * @slave_count:	current number of slaves known
180  * @attempts:		number of searches ran
181  * @slave_ttl:		number of searches before a slave is timed out
182  * @initialized:	prevent init/removal race conditions
183  * @id:			w1 bus number
184  * @search_count:	number of automatic searches to run, -1 unlimited
185  * @search_id:		allows continuing a search
186  * @refcnt:		reference count
187  * @priv:		private data storage
188  * @enable_pullup:	allows a strong pullup
189  * @pullup_duration:	time for the next strong pullup
190  * @flags:		one of w1_master_flags
191  * @thread:		thread for bus search and netlink commands
192  * @mutex:		protect most of w1_master
193  * @bus_mutex:		pretect concurrent bus access
194  * @driver:		sysfs driver
195  * @dev:		sysfs device
196  * @bus_master:		io operations available
197  * @seq:		sequence number used for netlink broadcasts
198  */
199 struct w1_master {
200 	struct list_head	w1_master_entry;
201 	struct module		*owner;
202 	unsigned char		name[W1_MAXNAMELEN];
203 	/* list_mutex protects just slist and async_list so slaves can be
204 	 * searched for and async commands added while the master has
205 	 * w1_master.mutex locked and is operating on the bus.
206 	 * lock order w1_mlock, w1_master.mutex, w1_master.list_mutex
207 	 */
208 	struct mutex		list_mutex;
209 	struct list_head	slist;
210 	struct list_head	async_list;
211 	int			max_slave_count, slave_count;
212 	unsigned long		attempts;
213 	int			slave_ttl;
214 	int			initialized;
215 	u32			id;
216 	int			search_count;
217 	/* id to start searching on, to continue a search or 0 to restart */
218 	u64			search_id;
219 
220 	atomic_t		refcnt;
221 
222 	void			*priv;
223 
224 	/** 5V strong pullup enabled flag, 1 enabled, zero disabled. */
225 	int			enable_pullup;
226 	/** 5V strong pullup duration in milliseconds, zero disabled. */
227 	int			pullup_duration;
228 
229 	long			flags;
230 
231 	struct task_struct	*thread;
232 	struct mutex		mutex;
233 	struct mutex		bus_mutex;
234 
235 	struct device_driver	*driver;
236 	struct device		dev;
237 
238 	struct w1_bus_master	*bus_master;
239 
240 	u32			seq;
241 };
242 
243 int w1_add_master_device(struct w1_bus_master *master);
244 void w1_remove_master_device(struct w1_bus_master *master);
245 
246 /**
247  * struct w1_family_ops - operations for a family type
248  * @add_slave: add_slave
249  * @remove_slave: remove_slave
250  * @groups: sysfs group
251  * @chip_info: pointer to struct hwmon_chip_info
252  */
253 struct w1_family_ops {
254 	int  (*add_slave)(struct w1_slave *sl);
255 	void (*remove_slave)(struct w1_slave *sl);
256 	const struct attribute_group **groups;
257 	const struct hwmon_chip_info *chip_info;
258 };
259 
260 /**
261  * struct w1_family - reference counted family structure.
262  * @family_entry:	family linked list
263  * @fid:		8 bit family identifier
264  * @fops:		operations for this family
265  * @of_match_table: open firmware match table
266  * @refcnt:		reference counter
267  */
268 struct w1_family {
269 	struct list_head	family_entry;
270 	u8			fid;
271 
272 	const struct w1_family_ops *fops;
273 
274 	const struct of_device_id *of_match_table;
275 
276 	atomic_t		refcnt;
277 };
278 
279 int w1_register_family(struct w1_family *family);
280 void w1_unregister_family(struct w1_family *family);
281 
282 /**
283  * module_w1_family() - Helper macro for registering a 1-Wire families
284  * @__w1_family: w1_family struct
285  *
286  * Helper macro for 1-Wire families which do not do anything special in module
287  * init/exit. This eliminates a lot of boilerplate. Each module may only
288  * use this macro once, and calling it replaces module_init() and module_exit()
289  */
290 #define module_w1_family(__w1_family) \
291 	module_driver(__w1_family, w1_register_family, \
292 			w1_unregister_family)
293 
294 u8 w1_triplet(struct w1_master *dev, int bdir);
295 u8 w1_touch_bit(struct w1_master *dev, int bit);
296 void w1_write_8(struct w1_master *, u8);
297 u8 w1_read_8(struct w1_master *);
298 int w1_reset_bus(struct w1_master *);
299 u8 w1_calc_crc8(u8 *, int);
300 void w1_write_block(struct w1_master *, const u8 *, int);
301 void w1_touch_block(struct w1_master *, u8 *, int);
302 u8 w1_read_block(struct w1_master *, u8 *, int);
303 int w1_reset_select_slave(struct w1_slave *sl);
304 int w1_reset_resume_command(struct w1_master *);
305 void w1_next_pullup(struct w1_master *, int);
306 
dev_to_w1_slave(struct device * dev)307 static inline struct w1_slave* dev_to_w1_slave(struct device *dev)
308 {
309 	return container_of(dev, struct w1_slave, dev);
310 }
311 
kobj_to_w1_slave(struct kobject * kobj)312 static inline struct w1_slave* kobj_to_w1_slave(struct kobject *kobj)
313 {
314 	return dev_to_w1_slave(container_of(kobj, struct device, kobj));
315 }
316 
dev_to_w1_master(struct device * dev)317 static inline struct w1_master* dev_to_w1_master(struct device *dev)
318 {
319 	return container_of(dev, struct w1_master, dev);
320 }
321 
322 #endif /* __KERNEL__ */
323 
324 #endif /* __LINUX_W1_H */
325