include/linux/w1.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /*
0003  * Copyright (c) 2004 Evgeniy Polyakov <zbr@ioremap.net>
0004  */
0005
0006 #ifndef __LINUX_W1_H
0007 #define __LINUX_W1_H
0008
0009 #include <linux/device.h>
0010
0011 /**
0012  * struct w1_reg_num - broken out slave device id
0013  *
0014  * @family: identifies the type of device
0015  * @id: along with family is the unique device id
0016  * @crc: checksum of the other bytes
0017  */
0018 struct w1_reg_num {
0019 #if defined(__LITTLE_ENDIAN_BITFIELD)
0020     __u64   family:8,
0021         id:48,
0022         crc:8;
0023 #elif defined(__BIG_ENDIAN_BITFIELD)
0024     __u64   crc:8,
0025         id:48,
0026         family:8;
0027 #else
0028 #error "Please fix <asm/byteorder.h>"
0029 #endif
0030 };
0031
0032 #ifdef __KERNEL__
0033
0034 #define W1_MAXNAMELEN       32
0035
0036 #define W1_SEARCH       0xF0
0037 #define W1_ALARM_SEARCH     0xEC
0038 #define W1_CONVERT_TEMP     0x44
0039 #define W1_SKIP_ROM     0xCC
0040 #define W1_COPY_SCRATCHPAD  0x48
0041 #define W1_WRITE_SCRATCHPAD 0x4E
0042 #define W1_READ_SCRATCHPAD  0xBE
0043 #define W1_READ_ROM     0x33
0044 #define W1_READ_PSUPPLY     0xB4
0045 #define W1_MATCH_ROM        0x55
0046 #define W1_RESUME_CMD       0xA5
0047
0048 /**
0049  * struct w1_slave - holds a single slave device on the bus
0050  *
0051  * @owner: Points to the one wire "wire" kernel module.
0052  * @name: Device id is ascii.
0053  * @w1_slave_entry: data for the linked list
0054  * @reg_num: the slave id in binary
0055  * @refcnt: reference count, delete when 0
0056  * @flags: bit flags for W1_SLAVE_ACTIVE W1_SLAVE_DETACH
0057  * @ttl: decrement per search this slave isn't found, deatch at 0
0058  * @master: bus which this slave is on
0059  * @family: module for device family type
0060  * @family_data: pointer for use by the family module
0061  * @dev: kernel device identifier
0062  * @hwmon: pointer to hwmon device
0063  *
0064  */
0065 struct w1_slave {
0066     struct module       *owner;
0067     unsigned char       name[W1_MAXNAMELEN];
0068     struct list_head    w1_slave_entry;
0069     struct w1_reg_num   reg_num;
0070     atomic_t        refcnt;
0071     int         ttl;
0072     unsigned long       flags;
0073
0074     struct w1_master    *master;
0075     struct w1_family    *family;
0076     void            *family_data;
0077     struct device       dev;
0078     struct device       *hwmon;
0079 };
0080
0081 typedef void (*w1_slave_found_callback)(struct w1_master *, u64);
0082
0083 /**
0084  * struct w1_bus_master - operations available on a bus master
0085  *
0086  * @data: the first parameter in all the functions below
0087  *
0088  * @read_bit: Sample the line level @return the level read (0 or 1)
0089  *
0090  * @write_bit: Sets the line level
0091  *
0092  * @touch_bit: the lowest-level function for devices that really support the
0093  * 1-wire protocol.
0094  * touch_bit(0) = write-0 cycle
0095  * touch_bit(1) = write-1 / read cycle
0096  * @return the bit read (0 or 1)
0097  *
0098  * @read_byte: Reads a bytes. Same as 8 touch_bit(1) calls.
0099  * @return the byte read
0100  *
0101  * @write_byte: Writes a byte. Same as 8 touch_bit(x) calls.
0102  *
0103  * @read_block: Same as a series of read_byte() calls
0104  * @return the number of bytes read
0105  *
0106  * @write_block: Same as a series of write_byte() calls
0107  *
0108  * @triplet: Combines two reads and a smart write for ROM searches
0109  * @return bit0=Id bit1=comp_id bit2=dir_taken
0110  *
0111  * @reset_bus: long write-0 with a read for the presence pulse detection
0112  * @return -1=Error, 0=Device present, 1=No device present
0113  *
0114  * @set_pullup: Put out a strong pull-up pulse of the specified duration.
0115  * @return -1=Error, 0=completed
0116  *
0117  * @search: Really nice hardware can handles the different types of ROM search
0118  * w1_master* is passed to the slave found callback.
0119  * u8 is search_type, W1_SEARCH or W1_ALARM_SEARCH
0120  *
0121  * @dev_id: Optional device id string, which w1 slaves could use for
0122  * creating names, which then give a connection to the w1 master
0123  *
0124  * Note: read_bit and write_bit are very low level functions and should only
0125  * be used with hardware that doesn't really support 1-wire operations,
0126  * like a parallel/serial port.
0127  * Either define read_bit and write_bit OR define, at minimum, touch_bit and
0128  * reset_bus.
0129  *
0130  */
0131 struct w1_bus_master {
0132     void        *data;
0133
0134     u8      (*read_bit)(void *);
0135
0136     void        (*write_bit)(void *, u8);
0137
0138     u8      (*touch_bit)(void *, u8);
0139
0140     u8      (*read_byte)(void *);
0141
0142     void        (*write_byte)(void *, u8);
0143
0144     u8      (*read_block)(void *, u8 *, int);
0145
0146     void        (*write_block)(void *, const u8 *, int);
0147
0148     u8      (*triplet)(void *, u8);
0149
0150     u8      (*reset_bus)(void *);
0151
0152     u8      (*set_pullup)(void *, int);
0153
0154     void        (*search)(void *, struct w1_master *,
0155         u8, w1_slave_found_callback);
0156
0157     char        *dev_id;
0158 };
0159
0160 /**
0161  * enum w1_master_flags - bitfields used in w1_master.flags
0162  * @W1_ABORT_SEARCH: abort searching early on shutdown
0163  * @W1_WARN_MAX_COUNT: limit warning when the maximum count is reached
0164  */
0165 enum w1_master_flags {
0166     W1_ABORT_SEARCH = 0,
0167     W1_WARN_MAX_COUNT = 1,
0168 };
0169
0170 /**
0171  * struct w1_master - one per bus master
0172  * @w1_master_entry:    master linked list
0173  * @owner:      module owner
0174  * @name:       dynamically allocate bus name
0175  * @list_mutex:     protect slist and async_list
0176  * @slist:      linked list of slaves
0177  * @async_list:     linked list of netlink commands to execute
0178  * @max_slave_count:    maximum number of slaves to search for at a time
0179  * @slave_count:    current number of slaves known
0180  * @attempts:       number of searches ran
0181  * @slave_ttl:      number of searches before a slave is timed out
0182  * @initialized:    prevent init/removal race conditions
0183  * @id:         w1 bus number
0184  * @search_count:   number of automatic searches to run, -1 unlimited
0185  * @search_id:      allows continuing a search
0186  * @refcnt:     reference count
0187  * @priv:       private data storage
0188  * @enable_pullup:  allows a strong pullup
0189  * @pullup_duration:    time for the next strong pullup
0190  * @flags:      one of w1_master_flags
0191  * @thread:     thread for bus search and netlink commands
0192  * @mutex:      protect most of w1_master
0193  * @bus_mutex:      pretect concurrent bus access
0194  * @driver:     sysfs driver
0195  * @dev:        sysfs device
0196  * @bus_master:     io operations available
0197  * @seq:        sequence number used for netlink broadcasts
0198  */
0199 struct w1_master {
0200     struct list_head    w1_master_entry;
0201     struct module       *owner;
0202     unsigned char       name[W1_MAXNAMELEN];
0203     /* list_mutex protects just slist and async_list so slaves can be
0204      * searched for and async commands added while the master has
0205      * w1_master.mutex locked and is operating on the bus.
0206      * lock order w1_mlock, w1_master.mutex, w1_master.list_mutex
0207      */
0208     struct mutex        list_mutex;
0209     struct list_head    slist;
0210     struct list_head    async_list;
0211     int         max_slave_count, slave_count;
0212     unsigned long       attempts;
0213     int         slave_ttl;
0214     int         initialized;
0215     u32         id;
0216     int         search_count;
0217     /* id to start searching on, to continue a search or 0 to restart */
0218     u64         search_id;
0219
0220     atomic_t        refcnt;
0221
0222     void            *priv;
0223
0224     /** 5V strong pullup enabled flag, 1 enabled, zero disabled. */
0225     int         enable_pullup;
0226     /** 5V strong pullup duration in milliseconds, zero disabled. */
0227     int         pullup_duration;
0228
0229     long            flags;
0230
0231     struct task_struct  *thread;
0232     struct mutex        mutex;
0233     struct mutex        bus_mutex;
0234
0235     struct device_driver    *driver;
0236     struct device       dev;
0237
0238     struct w1_bus_master    *bus_master;
0239
0240     u32         seq;
0241 };
0242
0243 int w1_add_master_device(struct w1_bus_master *master);
0244 void w1_remove_master_device(struct w1_bus_master *master);
0245
0246 /**
0247  * struct w1_family_ops - operations for a family type
0248  * @add_slave: add_slave
0249  * @remove_slave: remove_slave
0250  * @groups: sysfs group
0251  * @chip_info: pointer to struct hwmon_chip_info
0252  */
0253 struct w1_family_ops {
0254     int  (*add_slave)(struct w1_slave *sl);
0255     void (*remove_slave)(struct w1_slave *sl);
0256     const struct attribute_group **groups;
0257     const struct hwmon_chip_info *chip_info;
0258 };
0259
0260 /**
0261  * struct w1_family - reference counted family structure.
0262  * @family_entry:   family linked list
0263  * @fid:        8 bit family identifier
0264  * @fops:       operations for this family
0265  * @of_match_table: open firmware match table
0266  * @refcnt:     reference counter
0267  */
0268 struct w1_family {
0269     struct list_head    family_entry;
0270     u8          fid;
0271
0272     const struct w1_family_ops *fops;
0273
0274     const struct of_device_id *of_match_table;
0275
0276     atomic_t        refcnt;
0277 };
0278
0279 int w1_register_family(struct w1_family *family);
0280 void w1_unregister_family(struct w1_family *family);
0281
0282 /**
0283  * module_w1_family() - Helper macro for registering a 1-Wire families
0284  * @__w1_family: w1_family struct
0285  *
0286  * Helper macro for 1-Wire families which do not do anything special in module
0287  * init/exit. This eliminates a lot of boilerplate. Each module may only
0288  * use this macro once, and calling it replaces module_init() and module_exit()
0289  */
0290 #define module_w1_family(__w1_family) \
0291     module_driver(__w1_family, w1_register_family, \
0292             w1_unregister_family)
0293
0294 u8 w1_triplet(struct w1_master *dev, int bdir);
0295 u8 w1_touch_bit(struct w1_master *dev, int bit);
0296 void w1_write_8(struct w1_master *, u8);
0297 u8 w1_read_8(struct w1_master *);
0298 int w1_reset_bus(struct w1_master *);
0299 u8 w1_calc_crc8(u8 *, int);
0300 void w1_write_block(struct w1_master *, const u8 *, int);
0301 void w1_touch_block(struct w1_master *, u8 *, int);
0302 u8 w1_read_block(struct w1_master *, u8 *, int);
0303 int w1_reset_select_slave(struct w1_slave *sl);
0304 int w1_reset_resume_command(struct w1_master *);
0305 void w1_next_pullup(struct w1_master *, int);
0306
0307 static inline struct w1_slave* dev_to_w1_slave(struct device *dev)
0308 {
0309     return container_of(dev, struct w1_slave, dev);
0310 }
0311
0312 static inline struct w1_slave* kobj_to_w1_slave(struct kobject *kobj)
0313 {
0314     return dev_to_w1_slave(container_of(kobj, struct device, kobj));
0315 }
0316
0317 static inline struct w1_master* dev_to_w1_master(struct device *dev)
0318 {
0319     return container_of(dev, struct w1_master, dev);
0320 }
0321
0322 #endif /* __KERNEL__ */
0323
0324 #endif /* __LINUX_W1_H */