treewide: Replace GPLv2 boilerplate/reference with SPDX - rule 157
[sfrench/cifs-2.6.git] / include / linux / w1.h
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  * Note: read_bit and write_bit are very low level functions and should only
122  * be used with hardware that doesn't really support 1-wire operations,
123  * like a parallel/serial port.
124  * Either define read_bit and write_bit OR define, at minimum, touch_bit and
125  * reset_bus.
126  *
127  */
128 struct w1_bus_master {
129         void            *data;
130
131         u8              (*read_bit)(void *);
132
133         void            (*write_bit)(void *, u8);
134
135         u8              (*touch_bit)(void *, u8);
136
137         u8              (*read_byte)(void *);
138
139         void            (*write_byte)(void *, u8);
140
141         u8              (*read_block)(void *, u8 *, int);
142
143         void            (*write_block)(void *, const u8 *, int);
144
145         u8              (*triplet)(void *, u8);
146
147         u8              (*reset_bus)(void *);
148
149         u8              (*set_pullup)(void *, int);
150
151         void            (*search)(void *, struct w1_master *,
152                 u8, w1_slave_found_callback);
153 };
154
155 /**
156  * enum w1_master_flags - bitfields used in w1_master.flags
157  * @W1_ABORT_SEARCH: abort searching early on shutdown
158  * @W1_WARN_MAX_COUNT: limit warning when the maximum count is reached
159  */
160 enum w1_master_flags {
161         W1_ABORT_SEARCH = 0,
162         W1_WARN_MAX_COUNT = 1,
163 };
164
165 /**
166  * struct w1_master - one per bus master
167  * @w1_master_entry:    master linked list
168  * @owner:              module owner
169  * @name:               dynamically allocate bus name
170  * @list_mutex:         protect slist and async_list
171  * @slist:              linked list of slaves
172  * @async_list:         linked list of netlink commands to execute
173  * @max_slave_count:    maximum number of slaves to search for at a time
174  * @slave_count:        current number of slaves known
175  * @attempts:           number of searches ran
176  * @slave_ttl:          number of searches before a slave is timed out
177  * @initialized:        prevent init/removal race conditions
178  * @id:                 w1 bus number
179  * @search_count:       number of automatic searches to run, -1 unlimited
180  * @search_id:          allows continuing a search
181  * @refcnt:             reference count
182  * @priv:               private data storage
183  * @enable_pullup:      allows a strong pullup
184  * @pullup_duration:    time for the next strong pullup
185  * @flags:              one of w1_master_flags
186  * @thread:             thread for bus search and netlink commands
187  * @mutex:              protect most of w1_master
188  * @bus_mutex:          pretect concurrent bus access
189  * @driver:             sysfs driver
190  * @dev:                sysfs device
191  * @bus_master:         io operations available
192  * @seq:                sequence number used for netlink broadcasts
193  */
194 struct w1_master {
195         struct list_head        w1_master_entry;
196         struct module           *owner;
197         unsigned char           name[W1_MAXNAMELEN];
198         /* list_mutex protects just slist and async_list so slaves can be
199          * searched for and async commands added while the master has
200          * w1_master.mutex locked and is operating on the bus.
201          * lock order w1_mlock, w1_master.mutex, w1_master.list_mutex
202          */
203         struct mutex            list_mutex;
204         struct list_head        slist;
205         struct list_head        async_list;
206         int                     max_slave_count, slave_count;
207         unsigned long           attempts;
208         int                     slave_ttl;
209         int                     initialized;
210         u32                     id;
211         int                     search_count;
212         /* id to start searching on, to continue a search or 0 to restart */
213         u64                     search_id;
214
215         atomic_t                refcnt;
216
217         void                    *priv;
218
219         /** 5V strong pullup enabled flag, 1 enabled, zero disabled. */
220         int                     enable_pullup;
221         /** 5V strong pullup duration in milliseconds, zero disabled. */
222         int                     pullup_duration;
223
224         long                    flags;
225
226         struct task_struct      *thread;
227         struct mutex            mutex;
228         struct mutex            bus_mutex;
229
230         struct device_driver    *driver;
231         struct device           dev;
232
233         struct w1_bus_master    *bus_master;
234
235         u32                     seq;
236 };
237
238 int w1_add_master_device(struct w1_bus_master *master);
239 void w1_remove_master_device(struct w1_bus_master *master);
240
241 /**
242  * struct w1_family_ops - operations for a family type
243  * @add_slave: add_slave
244  * @remove_slave: remove_slave
245  * @groups: sysfs group
246  * @chip_info: pointer to struct hwmon_chip_info
247  */
248 struct w1_family_ops {
249         int  (*add_slave)(struct w1_slave *sl);
250         void (*remove_slave)(struct w1_slave *sl);
251         const struct attribute_group **groups;
252         const struct hwmon_chip_info *chip_info;
253 };
254
255 /**
256  * struct w1_family - reference counted family structure.
257  * @family_entry:       family linked list
258  * @fid:                8 bit family identifier
259  * @fops:               operations for this family
260  * @refcnt:             reference counter
261  */
262 struct w1_family {
263         struct list_head        family_entry;
264         u8                      fid;
265
266         struct w1_family_ops    *fops;
267
268         const struct of_device_id *of_match_table;
269
270         atomic_t                refcnt;
271 };
272
273 int w1_register_family(struct w1_family *family);
274 void w1_unregister_family(struct w1_family *family);
275
276 /**
277  * module_w1_driver() - Helper macro for registering a 1-Wire families
278  * @__w1_family: w1_family struct
279  *
280  * Helper macro for 1-Wire families which do not do anything special in module
281  * init/exit. This eliminates a lot of boilerplate. Each module may only
282  * use this macro once, and calling it replaces module_init() and module_exit()
283  */
284 #define module_w1_family(__w1_family) \
285         module_driver(__w1_family, w1_register_family, \
286                         w1_unregister_family)
287
288 u8 w1_triplet(struct w1_master *dev, int bdir);
289 u8 w1_touch_bit(struct w1_master *dev, int bit);
290 void w1_write_8(struct w1_master *, u8);
291 u8 w1_read_8(struct w1_master *);
292 int w1_reset_bus(struct w1_master *);
293 u8 w1_calc_crc8(u8 *, int);
294 void w1_write_block(struct w1_master *, const u8 *, int);
295 void w1_touch_block(struct w1_master *, u8 *, int);
296 u8 w1_read_block(struct w1_master *, u8 *, int);
297 int w1_reset_select_slave(struct w1_slave *sl);
298 int w1_reset_resume_command(struct w1_master *);
299 void w1_next_pullup(struct w1_master *, int);
300
301 static inline struct w1_slave* dev_to_w1_slave(struct device *dev)
302 {
303         return container_of(dev, struct w1_slave, dev);
304 }
305
306 static inline struct w1_slave* kobj_to_w1_slave(struct kobject *kobj)
307 {
308         return dev_to_w1_slave(container_of(kobj, struct device, kobj));
309 }
310
311 static inline struct w1_master* dev_to_w1_master(struct device *dev)
312 {
313         return container_of(dev, struct w1_master, dev);
314 }
315
316 #endif /* __KERNEL__ */
317
318 #endif /* __LINUX_W1_H */