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 */