include/linux/w1.h

   1 /*
   2  * Copyright (c) 2004 Evgeniy Polyakov <zbr@ioremap.net>
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  */
  14
  15 #ifndef __LINUX_W1_H
  16 #define __LINUX_W1_H
  17
  18 #include <linux/device.h>
  19
  20 /**
  21  * struct w1_reg_num - broken out slave device id
  22  *
  23  * @family: identifies the type of device
  24  * @id: along with family is the unique device id
  25  * @crc: checksum of the other bytes
  26  */
  27 struct w1_reg_num {
  28 #if defined(__LITTLE_ENDIAN_BITFIELD)
  29         __u64   family:8,
  30                 id:48,
  31                 crc:8;
  32 #elif defined(__BIG_ENDIAN_BITFIELD)
  33         __u64   crc:8,
  34                 id:48,
  35                 family:8;
  36 #else
  37 #error "Please fix <asm/byteorder.h>"
  38 #endif
  39 };
  40
  41 #ifdef __KERNEL__
  42
  43 #define W1_MAXNAMELEN           32
  44
  45 #define W1_SEARCH               0xF0
  46 #define W1_ALARM_SEARCH         0xEC
  47 #define W1_CONVERT_TEMP         0x44
  48 #define W1_SKIP_ROM             0xCC
  49 #define W1_COPY_SCRATCHPAD      0x48
  50 #define W1_WRITE_SCRATCHPAD     0x4E
  51 #define W1_READ_SCRATCHPAD      0xBE
  52 #define W1_READ_ROM             0x33
  53 #define W1_READ_PSUPPLY         0xB4
  54 #define W1_MATCH_ROM            0x55
  55 #define W1_RESUME_CMD           0xA5
  56
  57 /**
  58  * struct w1_slave - holds a single slave device on the bus
  59  *
  60  * @owner: Points to the one wire "wire" kernel module.
  61  * @name: Device id is ascii.
  62  * @w1_slave_entry: data for the linked list
  63  * @reg_num: the slave id in binary
  64  * @refcnt: reference count, delete when 0
  65  * @flags: bit flags for W1_SLAVE_ACTIVE W1_SLAVE_DETACH
  66  * @ttl: decrement per search this slave isn't found, deatch at 0
  67  * @master: bus which this slave is on
  68  * @family: module for device family type
  69  * @family_data: pointer for use by the family module
  70  * @dev: kernel device identifier
  71  * @hwmon: pointer to hwmon device
  72  *
  73  */
  74 struct w1_slave {
  75         struct module           *owner;
  76         unsigned char           name[W1_MAXNAMELEN];
  77         struct list_head        w1_slave_entry;
  78         struct w1_reg_num       reg_num;
  79         atomic_t                refcnt;
  80         int                     ttl;
  81         unsigned long           flags;
  82
  83         struct w1_master        *master;
  84         struct w1_family        *family;
  85         void                    *family_data;
  86         struct device           dev;
  87         struct device           *hwmon;
  88 };
  89
  90 typedef void (*w1_slave_found_callback)(struct w1_master *, u64);
  91
  92 /**
  93  * struct w1_bus_master - operations available on a bus master
  94  *
  95  * @data: the first parameter in all the functions below
  96  *
  97  * @read_bit: Sample the line level @return the level read (0 or 1)
  98  *
  99  * @write_bit: Sets the line level
 100  *
 101  * @touch_bit: the lowest-level function for devices that really support the
 102  * 1-wire protocol.
 103  * touch_bit(0) = write-0 cycle
 104  * touch_bit(1) = write-1 / read cycle
 105  * @return the bit read (0 or 1)
 106  *
 107  * @read_byte: Reads a bytes. Same as 8 touch_bit(1) calls.
 108  * @return the byte read
 109  *
 110  * @write_byte: Writes a byte. Same as 8 touch_bit(x) calls.
 111  *
 112  * @read_block: Same as a series of read_byte() calls
 113  * @return the number of bytes read
 114  *
 115  * @write_block: Same as a series of write_byte() calls
 116  *
 117  * @triplet: Combines two reads and a smart write for ROM searches
 118  * @return bit0=Id bit1=comp_id bit2=dir_taken
 119  *
 120  * @reset_bus: long write-0 with a read for the presence pulse detection
 121  * @return -1=Error, 0=Device present, 1=No device present
 122  *
 123  * @set_pullup: Put out a strong pull-up pulse of the specified duration.
 124  * @return -1=Error, 0=completed
 125  *
 126  * @search: Really nice hardware can handles the different types of ROM search
 127  * w1_master* is passed to the slave found callback.
 128  * u8 is search_type, W1_SEARCH or W1_ALARM_SEARCH
 129  *
 130  * Note: read_bit and write_bit are very low level functions and should only
 131  * be used with hardware that doesn't really support 1-wire operations,
 132  * like a parallel/serial port.
 133  * Either define read_bit and write_bit OR define, at minimum, touch_bit and
 134  * reset_bus.
 135  *
 136  */
 137 struct w1_bus_master {
 138         void            *data;
 139
 140         u8              (*read_bit)(void *);
 141
 142         void            (*write_bit)(void *, u8);
 143
 144         u8              (*touch_bit)(void *, u8);
 145
 146         u8              (*read_byte)(void *);
 147
 148         void            (*write_byte)(void *, u8);
 149
 150         u8              (*read_block)(void *, u8 *, int);
 151
 152         void            (*write_block)(void *, const u8 *, int);
 153
 154         u8              (*triplet)(void *, u8);
 155
 156         u8              (*reset_bus)(void *);
 157
 158         u8              (*set_pullup)(void *, int);
 159
 160         void            (*search)(void *, struct w1_master *,
 161                 u8, w1_slave_found_callback);
 162 };
 163
 164 /**
 165  * enum w1_master_flags - bitfields used in w1_master.flags
 166  * @W1_ABORT_SEARCH: abort searching early on shutdown
 167  * @W1_WARN_MAX_COUNT: limit warning when the maximum count is reached
 168  */
 169 enum w1_master_flags {
 170         W1_ABORT_SEARCH = 0,
 171         W1_WARN_MAX_COUNT = 1,
 172 };
 173
 174 /**
 175  * struct w1_master - one per bus master
 176  * @w1_master_entry:    master linked list
 177  * @owner:              module owner
 178  * @name:               dynamically allocate bus name
 179  * @list_mutex:         protect slist and async_list
 180  * @slist:              linked list of slaves
 181  * @async_list:         linked list of netlink commands to execute
 182  * @max_slave_count:    maximum number of slaves to search for at a time
 183  * @slave_count:        current number of slaves known
 184  * @attempts:           number of searches ran
 185  * @slave_ttl:          number of searches before a slave is timed out
 186  * @initialized:        prevent init/removal race conditions
 187  * @id:                 w1 bus number
 188  * @search_count:       number of automatic searches to run, -1 unlimited
 189  * @search_id:          allows continuing a search
 190  * @refcnt:             reference count
 191  * @priv:               private data storage
 192  * @enable_pullup:      allows a strong pullup
 193  * @pullup_duration:    time for the next strong pullup
 194  * @flags:              one of w1_master_flags
 195  * @thread:             thread for bus search and netlink commands
 196  * @mutex:              protect most of w1_master
 197  * @bus_mutex:          pretect concurrent bus access
 198  * @driver:             sysfs driver
 199  * @dev:                sysfs device
 200  * @bus_master:         io operations available
 201  * @seq:                sequence number used for netlink broadcasts
 202  */
 203 struct w1_master {
 204         struct list_head        w1_master_entry;
 205         struct module           *owner;
 206         unsigned char           name[W1_MAXNAMELEN];
 207         /* list_mutex protects just slist and async_list so slaves can be
 208          * searched for and async commands added while the master has
 209          * w1_master.mutex locked and is operating on the bus.
 210          * lock order w1_mlock, w1_master.mutex, w1_master.list_mutex
 211          */
 212         struct mutex            list_mutex;
 213         struct list_head        slist;
 214         struct list_head        async_list;
 215         int                     max_slave_count, slave_count;
 216         unsigned long           attempts;
 217         int                     slave_ttl;
 218         int                     initialized;
 219         u32                     id;
 220         int                     search_count;
 221         /* id to start searching on, to continue a search or 0 to restart */
 222         u64                     search_id;
 223
 224         atomic_t                refcnt;
 225
 226         void                    *priv;
 227
 228         /** 5V strong pullup enabled flag, 1 enabled, zero disabled. */
 229         int                     enable_pullup;
 230         /** 5V strong pullup duration in milliseconds, zero disabled. */
 231         int                     pullup_duration;
 232
 233         long                    flags;
 234
 235         struct task_struct      *thread;
 236         struct mutex            mutex;
 237         struct mutex            bus_mutex;
 238
 239         struct device_driver    *driver;
 240         struct device           dev;
 241
 242         struct w1_bus_master    *bus_master;
 243
 244         u32                     seq;
 245 };
 246
 247 int w1_add_master_device(struct w1_bus_master *master);
 248 void w1_remove_master_device(struct w1_bus_master *master);
 249
 250 /**
 251  * struct w1_family_ops - operations for a family type
 252  * @add_slave: add_slave
 253  * @remove_slave: remove_slave
 254  * @groups: sysfs group
 255  * @chip_info: pointer to struct hwmon_chip_info
 256  */
 257 struct w1_family_ops {
 258         int  (*add_slave)(struct w1_slave *sl);
 259         void (*remove_slave)(struct w1_slave *sl);
 260         const struct attribute_group **groups;
 261         const struct hwmon_chip_info *chip_info;
 262 };
 263
 264 /**
 265  * struct w1_family - reference counted family structure.
 266  * @family_entry:       family linked list
 267  * @fid:                8 bit family identifier
 268  * @fops:               operations for this family
 269  * @refcnt:             reference counter
 270  */
 271 struct w1_family {
 272         struct list_head        family_entry;
 273         u8                      fid;
 274
 275         struct w1_family_ops    *fops;
 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_driver() - 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 */