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