w1: format for DocBook and fixes

	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \

	    80211.xml debugobjects.xml sh.xml regulator.xml \

	    alsa-driver-api.xml writing-an-alsa-driver.xml \

	    tracepoint.xml drm.xml media_api.xml

	    tracepoint.xml drm.xml media_api.xml w1.xml

include $(srctree)/Documentation/DocBook/media/Makefile

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"

	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<book id="w1id">

  <bookinfo>

    <title>W1: Dallas' 1-wire bus</title>

    <authorgroup>

      <author>

        <firstname>David</firstname>

        <surname>Fries</surname>

        <affiliation>

          <address>

            <email>David@Fries.net</email>

          </address>

        </affiliation>

      </author>

    </authorgroup>

    <copyright>

      <year>2013</year>

      <!--

      <holder></holder>

      -->

    </copyright>

    <legalnotice>

      <para>

        This documentation is free software; you can redistribute

        it and/or modify it under the terms of the GNU General Public

        License version 2.

      </para>

      <para>

        This program is distributed in the hope that it will be

        useful, but WITHOUT ANY WARRANTY; without even the implied

        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

        For more details see the file COPYING in the source

        distribution of Linux.

      </para>

    </legalnotice>

  </bookinfo>

  <toc></toc>

  <chapter id="w1_internal">

    <title>W1 API internal to the kernel</title>

    <sect1 id="w1_internal_api">

      <title>W1 API internal to the kernel</title>

      <sect2 id="w1.h">

        <title>drivers/w1/w1.h</title>

        <para>W1 core functions.</para>

!Idrivers/w1/w1.h

      </sect2>

      <sect2 id="w1.c">

        <title>drivers/w1/w1.c</title>

        <para>W1 core functions.</para>

!Idrivers/w1/w1.c

      </sect2>

      <sect2 id="w1_family.h">

        <title>drivers/w1/w1_family.h</title>

        <para>Allows registering device family operations.</para>

!Idrivers/w1/w1_family.h

      </sect2>

      <sect2 id="w1_family.c">

        <title>drivers/w1/w1_family.c</title>

        <para>Allows registering device family operations.</para>

!Edrivers/w1/w1_family.c

      </sect2>

      <sect2 id="w1_int.c">

        <title>drivers/w1/w1_int.c</title>

        <para>W1 internal initialization for master devices.</para>

!Edrivers/w1/w1_int.c

      </sect2>

      <sect2 id="w1_netlink.h">

        <title>drivers/w1/w1_netlink.h</title>

        <para>W1 external netlink API structures and commands.</para>

!Idrivers/w1/w1_netlink.h

      </sect2>

      <sect2 id="w1_io.c">

        <title>drivers/w1/w1_io.c</title>

        <para>W1 input/output.</para>

!Edrivers/w1/w1_io.c

!Idrivers/w1/w1_io.c

      </sect2>

    </sect1>

  </chapter>

</book>

=============

There are three types of messages between w1 core and userspace:

1. Events. They are generated each time new master or slave device

	found either due to automatic or requested search.

1. Events. They are generated each time a new master or slave device

	is found either due to automatic or requested search.

2. Userspace commands.

3. Replies to userspace commands.

of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd).

If reply is generated for master or root command (which do not have

w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg

structires.

structures.

w1_netlink_msg.status field will carry positive error value

(EINVAL for example) or zero in case of success.

Then all requested in w1_netlink_msg operations are performed one by one.

If command requires reply (like read command) it is sent on command completion.

When all commands (w1_netlink_cmd) are processed muster device is unlocked

When all commands (w1_netlink_cmd) are processed master device is unlocked

and next w1_netlink_msg header processing started.

int w1_max_slave_ttl = 10;

module_param_named(timeout, w1_timeout, int, 0);

MODULE_PARM_DESC(timeout, "time in seconds between automatic slave searches");

/* A search stops when w1_max_slave_count devices have been found in that

 * search.  The next search will start over and detect the same set of devices

 * on a static 1-wire bus.  Memory is not allocated based on this number, just

 * on the number of devices known to the kernel.  Having a high number does not

 * consume additional resources.  As a special case, if there is only one

 * device on the network and w1_max_slave_count is set to 1, the device id can

 * be read directly skipping the normal slower search process.

 */

module_param_named(max_slave_count, w1_max_slave_count, int, 0);

MODULE_PARM_DESC(max_slave_count,

	"maximum number of slaves detected in a search");

module_param_named(slave_ttl, w1_max_slave_ttl, int, 0);

MODULE_PARM_DESC(slave_ttl,

	"Number of searches not seeing a slave before it will be removed");

DEFINE_MUTEX(w1_mlock);

LIST_HEAD(w1_masters);

}

/**

 * Performs a ROM Search & registers any devices found.

 * w1_search() - Performs a ROM Search & registers any devices found.

 * @dev: The master device to search

 * @search_type: W1_SEARCH to search all devices, or W1_ALARM_SEARCH

 * to return only devices in the alarmed state

 * @cb: Function to call when a device is found

 *

 * The 1-wire search is a simple binary tree search.

 * For each bit of the address, we read two bits and write one bit.

 * The bit written will put to sleep all devies that don't match that bit.

 *

 * See "Application note 187 1-wire search algorithm" at www.maxim-ic.com

 *

 * @dev        The master device to search

 * @cb         Function to call when a device is found

 */

void w1_search(struct w1_master *dev, u8 search_type, w1_slave_found_callback cb)

{

			else

				search_bit = ((last_rn >> i) & 0x1);

			/** Read two bits and write one bit */

			/* Read two bits and write one bit */

			triplet_ret = w1_triplet(dev, search_bit);

			/* quit if no device responded */

	w1_search_process_cb(dev, search_type, w1_slave_found);

}

/**

 * w1_process_callbacks() - execute each dev->async_list callback entry

 * @dev: w1_master device

 *

 * Return: 1 if there were commands to executed 0 otherwise

 */

int w1_process_callbacks(struct w1_master *dev)

{

	int ret = 0;

#ifndef __W1_H

#define __W1_H

/**

 * struct w1_reg_num - broken out slave device id

 *

 * @family: identifies the type of device

 * @id: along with family is the unique device id

 * @crc: checksum of the other bytes

 */

struct w1_reg_num

{

#if defined(__LITTLE_ENDIAN_BITFIELD)

#define W1_SLAVE_ACTIVE		0

#define W1_SLAVE_DETACH		1

/**

 * struct w1_slave - holds a single slave device on the bus

 *

 * @owner: Points to the one wire "wire" kernel module.

 * @name: Device id is ascii.

 * @w1_slave_entry: data for the linked list

 * @reg_num: the slave id in binary

 * @refcnt: reference count, delete when 0

 * @flags: bit flags for W1_SLAVE_ACTIVE W1_SLAVE_DETACH

 * @ttl: decrement per search this slave isn't found, deatch at 0

 * @master: bus which this slave is on

 * @family: module for device family type

 * @family_data: pointer for use by the family module

 * @dev: kernel device identifier

 *

 */

struct w1_slave

{

	struct module		*owner;

/**

 * struct w1_bus_master - operations available on a bus master

 *

 * @data: the first parameter in all the functions below

 *

 * @read_bit: Sample the line level @return the level read (0 or 1)

 *

 * @write_bit: Sets the line level

 *

 * @touch_bit: the lowest-level function for devices that really support the

 * 1-wire protocol.

 * touch_bit(0) = write-0 cycle

 * touch_bit(1) = write-1 / read cycle

 * @return the bit read (0 or 1)

 *

 * @read_byte: Reads a bytes. Same as 8 touch_bit(1) calls.

 * @return the byte read

 *

 * @write_byte: Writes a byte. Same as 8 touch_bit(x) calls.

 *

 * @read_block: Same as a series of read_byte() calls

 * @return the number of bytes read

 *

 * @write_block: Same as a series of write_byte() calls

 *

 * @triplet: Combines two reads and a smart write for ROM searches

 * @return bit0=Id bit1=comp_id bit2=dir_taken

 *

 * @reset_bus: long write-0 with a read for the presence pulse detection

 * @return -1=Error, 0=Device present, 1=No device present

 *

 * @set_pullup: Put out a strong pull-up pulse of the specified duration.

 * @return -1=Error, 0=completed

 *

 * @search: Really nice hardware can handles the different types of ROM search

 * w1_master* is passed to the slave found callback.

 * u8 is search_type, W1_SEARCH or W1_ALARM_SEARCH

 *

 * Note: read_bit and write_bit are very low level functions and should only

 * be used with hardware that doesn't really support 1-wire operations,

 * like a parallel/serial port.

 * Either define read_bit and write_bit OR define, at minimum, touch_bit and

 * reset_bus.

 *

 */

struct w1_bus_master

{

	/** the first parameter in all the functions below */

	void		*data;

	/**

	 * Sample the line level

	 * @return the level read (0 or 1)

	 */

	u8		(*read_bit)(void *);

	/** Sets the line level */

	void		(*write_bit)(void *, u8);

	/**

	 * touch_bit is the lowest-level function for devices that really

	 * support the 1-wire protocol.

	 * touch_bit(0) = write-0 cycle

	 * touch_bit(1) = write-1 / read cycle

	 * @return the bit read (0 or 1)

	 */

	u8		(*touch_bit)(void *, u8);

	/**

	 * Reads a bytes. Same as 8 touch_bit(1) calls.

	 * @return the byte read

	 */

	u8		(*read_byte)(void *);

	/**

	 * Writes a byte. Same as 8 touch_bit(x) calls.

	 */

	void		(*write_byte)(void *, u8);

	/**

	 * Same as a series of read_byte() calls

	 * @return the number of bytes read

	 */

	u8		(*read_block)(void *, u8 *, int);

	/** Same as a series of write_byte() calls */

	void		(*write_block)(void *, const u8 *, int);

	/**

	 * Combines two reads and a smart write for ROM searches

	 * @return bit0=Id bit1=comp_id bit2=dir_taken

	 */

	u8		(*triplet)(void *, u8);

	/**

	 * long write-0 with a read for the presence pulse detection

	 * @return -1=Error, 0=Device present, 1=No device present

	 */

	u8		(*reset_bus)(void *);

	/**

	 * Put out a strong pull-up pulse of the specified duration.

	 * @return -1=Error, 0=completed

	 */

	u8		(*set_pullup)(void *, int);

	/** Really nice hardware can handles the different types of ROM search

	 *  w1_master* is passed to the slave found callback.

	 *  u8 is search_type, W1_SEARCH or W1_ALARM_SEARCH

	 */

	void		(*search)(void *, struct w1_master *,

		u8, w1_slave_found_callback);

};

	W1_WARN_MAX_COUNT = 1,

};

/**

 * struct w1_master - one per bus master

 * @w1_master_entry:	master linked list

 * @owner:		module owner

 * @name:		dynamically allocate bus name

 * @list_mutex:		protect slist and async_list

 * @slist:		linked list of slaves

 * @async_list:		linked list of netlink commands to execute

 * @max_slave_count:	maximum number of slaves to search for at a time

 * @slave_count:	current number of slaves known

 * @attempts:		number of searches ran

 * @slave_ttl:		number of searches before a slave is timed out

 * @initialized:	prevent init/removal race conditions

 * @id:			w1 bus number

 * @search_count:	number of automatic searches to run, -1 unlimited

 * @search_id:		allows continuing a search

 * @refcnt:		reference count

 * @priv:		private data storage

 * @priv_size:		size allocated

 * @enable_pullup:	allows a strong pullup

 * @pullup_duration:	time for the next strong pullup

 * @flags:		one of w1_master_flags

 * @thread:		thread for bus search and netlink commands

 * @mutex:		protect most of w1_master

 * @bus_mutex:		pretect concurrent bus access

 * @driver:		sysfs driver

 * @dev:		sysfs device

 * @bus_master:		io operations available

 * @seq:		sequence number used for netlink broadcasts

 * @portid:		destination for the current netlink command

 */

struct w1_master

{

	struct list_head	w1_master_entry;

	/* list_mutex protects just slist and async_list so slaves can be

	 * searched for and async commands added while the master has

	 * w1_master.mutex locked and is operating on the bus.

	 * lock order w1_mlock, w1_master.mutex, w1_master_list_mutex

	 * lock order w1_mlock, w1_master.mutex, w1_master.list_mutex

	 */

	struct mutex		list_mutex;

	struct list_head	slist;

extern struct list_head w1_masters;

extern struct mutex w1_mlock;

/* returns 1 if there were commands to executed 0 otherwise */

extern int w1_process_callbacks(struct w1_master *dev);

extern int w1_process(void *);