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