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