1 files changed, 126 insertions, 38 deletions
diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1.netlink
index 3640c7c87d45..804445f745ed 100644
--- a/Documentation/w1/w1.netlink
+++ b/Documentation/w1/w1.netlink
@@ -5,69 +5,157 @@ Message types.
 =============
 There are three types of messages between w1 core and userspace:
-1. Events. They are generated each time new master or slave device found
+1. Events. They are generated each time new master or slave device
-        either due to automatic or requested search.
+        found either due to automatic or requested search.
-2. Userspace commands. Includes read/write and search/alarm search comamnds.
+2. Userspace commands.
 3. Replies to userspace commands.
 Protocol.
 ========
-[struct cn_msg] - connector header. It's length field is equal to size of the attached data.
+[struct cn_msg] - connector header.
+        Its length field is equal to size of the attached data
 [struct w1_netlink_msg] - w1 netlink header.
        __u8 type       - message type.
-                        W1_SLAVE_ADD/W1_SLAVE_REMOVE - slave add/remove events.
+                        W1_LIST_MASTERS
-                        W1_MASTER_ADD/W1_MASTER_REMOVE - master add/remove events.
+                                list current bus masters
-                        W1_MASTER_CMD - userspace command for bus master device (search/alarm search).
+                        W1_SLAVE_ADD/W1_SLAVE_REMOVE
-                        W1_SLAVE_CMD - userspace command for slave device (read/write/ search/alarm search
+                                slave add/remove events
-                                        for bus master device where given slave device found).
+                        W1_MASTER_ADD/W1_MASTER_REMOVE
+                                master add/remove events
+                        W1_MASTER_CMD
+                                userspace command for bus master
+                                device (search/alarm search)
+                        W1_SLAVE_CMD
+                                userspace command for slave device
+                                (read/write/touch)
        __u8 res        - reserved
-        __u16 len       - size of attached to this header data.
+        __u16 len       - size of data attached to this header data
        union {
-                __u8 id;                         - slave unique device id
+                __u8 id[8];                      - slave unique device id
                struct w1_mst {
-                        __u32           id;      - master's id.
+                        __u32           id;      - master's id
                        __u32           res;     - reserved
                } mst;
        } id;
-[strucrt w1_netlink_cmd] - command for gived master or slave device.
+[struct w1_netlink_cmd] - command for given master or slave device.
        __u8 cmd        - command opcode.
-                        W1_CMD_READ     - read command.
+                        W1_CMD_READ     - read command
-                        W1_CMD_WRITE    - write command.
+                        W1_CMD_WRITE    - write command
-                        W1_CMD_SEARCH   - search command.
+                        W1_CMD_TOUCH    - touch command
-                        W1_CMD_ALARM_SEARCH - alarm search command.
+                                (write and sample data back to userspace)
+                        W1_CMD_SEARCH   - search command
+                        W1_CMD_ALARM_SEARCH - alarm search command
        __u8 res        - reserved
-        __u16 len       - length of data for this command.
+        __u16 len       - length of data for this command
-                        For read command data must be allocated like for write command.
+                For read command data must be allocated like for write command
-        __u8 data[0]    - data for this command.
+        __u8 data[0]    - data for this command
-Each connector message can include one or more w1_netlink_msg with zero of more attached w1_netlink_cmd messages.
+Each connector message can include one or more w1_netlink_msg with
+zero or more attached w1_netlink_cmd messages.
-For event messages there are no w1_netlink_cmd embedded structures, only connector header
+For event messages there are no w1_netlink_cmd embedded structures,
-and w1_netlink_msg strucutre with "len" field being zero and filled type (one of event types)
+only connector header and w1_netlink_msg strucutre with "len" field
-and id - either 8 bytes of slave unique id in host order, or master's id, which is assigned
+being zero and filled type (one of event types) and id:
-to bus master device when it is added to w1 core.
+either 8 bytes of slave unique id in host order,
+or master's id, which is assigned to bus master device
+when it is added to w1 core.
+Currently replies to userspace commands are only generated for read
+command request. One reply is generated exactly for one w1_netlink_cmd
+read request. Replies are not combined when sent - i.e. typical reply
+messages looks like the following:
-Currently replies to userspace commands are only generated for read command request.
-One reply is generated exactly for one w1_netlink_cmd read request.
-Replies are not combined when sent - i.e. typical reply messages looks like the following:
 [cn_msg][w1_netlink_msg][w1_netlink_cmd]
-cn_msg.len = sizeof(struct w1_netlink_msg) + sizeof(struct w1_netlink_cmd) + cmd->len;
+cn_msg.len = sizeof(struct w1_netlink_msg) +
+             sizeof(struct w1_netlink_cmd) +
+             cmd->len;
 w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
 w1_netlink_cmd.len = cmd->len;
+Replies to W1_LIST_MASTERS should send a message back to the userspace
+which will contain list of all registered master ids in the following
+format:
+        cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
+        w1_netlink_msg) plus number of masters multipled by 4)
+        w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to
+                number of masters multiplied by 4 (u32 size))
+        id0 ... idN
+        Each message is at most 4k in size, so if number of master devices
+        exceeds this, it will be split into several messages,
+        cn.seq will be increased for each one.
+W1 search and alarm search commands.
+request:
+[cn_msg]
+  [w1_netlink_msg type = W1_MASTER_CMD
+        id is equal to the bus master id to use for searching]
+  [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
+reply:
+  [cn_msg, ack = 1 and increasing, 0 means the last message,
+        seq is equal to the request seq]
+  [w1_netlink_msg type = W1_MASTER_CMD]
+  [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
+        len is equal to number of IDs multiplied by 8]
+  [64bit-id0 ... 64bit-idN]
+Length in each header corresponds to the size of the data behind it, so
+w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
+        Can be zero.
+w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
+cn_msg->len = sizeof(struct w1_netlink_msg) +
+              sizeof(struct w1_netlink_cmd) +
+              N*8;
+W1 reset command.
+[cn_msg]
+  [w1_netlink_msg type = W1_MASTER_CMD
+        id is equal to the bus master id to use for searching]
+  [w1_netlink_cmd cmd = W1_CMD_RESET]
+Command status replies.
+======================
+Each command (either root, master or slave with or without w1_netlink_cmd
+structure) will be 'acked' by the w1 core. Format of the reply is the same
+as request message except that length parameters do not account for data
+requested by the user, i.e. read/write/touch IO requests will not contain
+data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size
+of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum
+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.
+w1_netlink_msg.status field will carry positive error value
+(EINVAL for example) or zero in case of success.
+All other fields in every structure will mirror the same parameters in the
+request message (except lengths as described above).
+Status reply is generated for every w1_netlink_cmd embedded in the
+w1_netlink_msg, if there are no w1_netlink_cmd structures,
+reply will be generated for the w1_netlink_msg.
+All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
+even if there were errors, only length mismatch interrupts message processing.
 Operation steps in w1 core when new command is received.
 =======================================================
-When new message (w1_netlink_msg) is received w1 core detects if it is master of slave request,
+When new message (w1_netlink_msg) is received w1 core detects if it is
-according to w1_netlink_msg.type field.
+master or slave request, according to w1_netlink_msg.type field.
 Then master or slave device is searched for.
-When found, master device (requested or those one on where slave device is found) is locked.
+When found, master device (requested or those one on where slave device
-If slave command is requested, then reset/select procedure is started to select given device.
+is found) is locked. If slave command is requested, then reset/select
+procedure is started to select given device.
 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.
@@ -82,8 +170,8 @@ Connector [1] specific documentation.
 Each connector message includes two u32 fields as "address".
 w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
 Each message also includes sequence and acknowledge numbers.
-Sequence number for event messages is appropriate bus master sequence number increased with
+Sequence number for event messages is appropriate bus master sequence number
-each event message sent "through" this master.
+increased with each event message sent "through" this master.
 Sequence number for userspace requests is set by userspace application.
 Sequence number for reply is the same as was in request, and
 acknowledge number is set to seq+1.
@@ -93,6 +181,6 @@ Additional documantion, source code examples.
 ============================================
 1. Documentation/connector
-2. http://tservice.net.ru/~s0mbre/archive/w1
+2. http://www.ioremap.net/archive/w1
-This archive includes userspace application w1d.c which
+This archive includes userspace application w1d.c which uses
-uses read/write/search commands for all master/slave devices found on the bus.
+read/write/search commands for all master/slave devices found on the bus.

diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1.netlink index 3640c7c87d45..804445f745ed 100644 --- a/Documentation/w1/w1.netlink +++ b/Documentation/w1/w1.netlink
@@ -5,69 +5,157 @@ Message types.
5	=============	5	=============
6		6
7	There are three types of messages between w1 core and userspace:	7	There are three types of messages between w1 core and userspace:
8	1. Events. They are generated each time new master or slave device found	8	1. Events. They are generated each time new master or slave device
9	either due to automatic or requested search.	9	found either due to automatic or requested search.
10	2. Userspace commands. Includes read/write and search/alarm search comamnds.	10	2. Userspace commands.
11	3. Replies to userspace commands.	11	3. Replies to userspace commands.
12		12
13		13
14	Protocol.	14	Protocol.
15	========	15	========
16		16
17	[struct cn_msg] - connector header. It's length field is equal to size of the attached data.	17	[struct cn_msg] - connector header.
		18	Its length field is equal to size of the attached data
18	[struct w1_netlink_msg] - w1 netlink header.	19	[struct w1_netlink_msg] - w1 netlink header.
19	__u8 type - message type.	20	__u8 type - message type.
20	W1_SLAVE_ADD/W1_SLAVE_REMOVE - slave add/remove events.	21	W1_LIST_MASTERS
21	W1_MASTER_ADD/W1_MASTER_REMOVE - master add/remove events.	22	list current bus masters
22	W1_MASTER_CMD - userspace command for bus master device (search/alarm search).	23	W1_SLAVE_ADD/W1_SLAVE_REMOVE
23	W1_SLAVE_CMD - userspace command for slave device (read/write/ search/alarm search	24	slave add/remove events
24	for bus master device where given slave device found).	25	W1_MASTER_ADD/W1_MASTER_REMOVE
		26	master add/remove events
		27	W1_MASTER_CMD
		28	userspace command for bus master
		29	device (search/alarm search)
		30	W1_SLAVE_CMD
		31	userspace command for slave device
		32	(read/write/touch)
25	__u8 res - reserved	33	__u8 res - reserved
26	__u16 len - size of attached to this header data.	34	__u16 len - size of data attached to this header data
27	union {	35	union {
28	__u8 id; - slave unique device id	36	__u8 id[8]; - slave unique device id
29	struct w1_mst {	37	struct w1_mst {
30	__u32 id; - master's id.	38	__u32 id; - master's id
31	__u32 res; - reserved	39	__u32 res; - reserved
32	} mst;	40	} mst;
33	} id;	41	} id;
34		42
35	[strucrt w1_netlink_cmd] - command for gived master or slave device.	43	[struct w1_netlink_cmd] - command for given master or slave device.
36	__u8 cmd - command opcode.	44	__u8 cmd - command opcode.
37	W1_CMD_READ - read command.	45	W1_CMD_READ - read command
38	W1_CMD_WRITE - write command.	46	W1_CMD_WRITE - write command
39	W1_CMD_SEARCH - search command.	47	W1_CMD_TOUCH - touch command
40	W1_CMD_ALARM_SEARCH - alarm search command.	48	(write and sample data back to userspace)
		49	W1_CMD_SEARCH - search command
		50	W1_CMD_ALARM_SEARCH - alarm search command
41	__u8 res - reserved	51	__u8 res - reserved
42	__u16 len - length of data for this command.	52	__u16 len - length of data for this command
43	For read command data must be allocated like for write command.	53	For read command data must be allocated like for write command
44	__u8 data[0] - data for this command.	54	__u8 data[0] - data for this command
45		55
46		56
47	Each connector message can include one or more w1_netlink_msg with zero of more attached w1_netlink_cmd messages.	57	Each connector message can include one or more w1_netlink_msg with
		58	zero or more attached w1_netlink_cmd messages.
48		59
49	For event messages there are no w1_netlink_cmd embedded structures, only connector header	60	For event messages there are no w1_netlink_cmd embedded structures,
50	and w1_netlink_msg strucutre with "len" field being zero and filled type (one of event types)	61	only connector header and w1_netlink_msg strucutre with "len" field
51	and id - either 8 bytes of slave unique id in host order, or master's id, which is assigned	62	being zero and filled type (one of event types) and id:
52	to bus master device when it is added to w1 core.	63	either 8 bytes of slave unique id in host order,
		64	or master's id, which is assigned to bus master device
		65	when it is added to w1 core.
		66
		67	Currently replies to userspace commands are only generated for read
		68	command request. One reply is generated exactly for one w1_netlink_cmd
		69	read request. Replies are not combined when sent - i.e. typical reply
		70	messages looks like the following:
53		71
54	Currently replies to userspace commands are only generated for read command request.
55	One reply is generated exactly for one w1_netlink_cmd read request.
56	Replies are not combined when sent - i.e. typical reply messages looks like the following:
57	[cn_msg][w1_netlink_msg][w1_netlink_cmd]	72	[cn_msg][w1_netlink_msg][w1_netlink_cmd]
58	cn_msg.len = sizeof(struct w1_netlink_msg) + sizeof(struct w1_netlink_cmd) + cmd->len;	73	cn_msg.len = sizeof(struct w1_netlink_msg) +
		74	sizeof(struct w1_netlink_cmd) +
		75	cmd->len;
59	w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;	76	w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
60	w1_netlink_cmd.len = cmd->len;	77	w1_netlink_cmd.len = cmd->len;
61		78
		79	Replies to W1_LIST_MASTERS should send a message back to the userspace
		80	which will contain list of all registered master ids in the following
		81	format:
		82
		83	cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
		84	w1_netlink_msg) plus number of masters multipled by 4)
		85	w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to
		86	number of masters multiplied by 4 (u32 size))
		87	id0 ... idN
		88
		89	Each message is at most 4k in size, so if number of master devices
		90	exceeds this, it will be split into several messages,
		91	cn.seq will be increased for each one.
		92
		93	W1 search and alarm search commands.
		94	request:
		95	[cn_msg]
		96	[w1_netlink_msg type = W1_MASTER_CMD
		97	id is equal to the bus master id to use for searching]
		98	[w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
		99
		100	reply:
		101	[cn_msg, ack = 1 and increasing, 0 means the last message,
		102	seq is equal to the request seq]
		103	[w1_netlink_msg type = W1_MASTER_CMD]
		104	[w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
		105	len is equal to number of IDs multiplied by 8]
		106	[64bit-id0 ... 64bit-idN]
		107	Length in each header corresponds to the size of the data behind it, so
		108	w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
		109	Can be zero.
		110	w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
		111	cn_msg->len = sizeof(struct w1_netlink_msg) +
		112	sizeof(struct w1_netlink_cmd) +
		113	N*8;
		114
		115	W1 reset command.
		116	[cn_msg]
		117	[w1_netlink_msg type = W1_MASTER_CMD
		118	id is equal to the bus master id to use for searching]
		119	[w1_netlink_cmd cmd = W1_CMD_RESET]
		120
		121
		122	Command status replies.
		123	======================
		124
		125	Each command (either root, master or slave with or without w1_netlink_cmd
		126	structure) will be 'acked' by the w1 core. Format of the reply is the same
		127	as request message except that length parameters do not account for data
		128	requested by the user, i.e. read/write/touch IO requests will not contain
		129	data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size
		130	of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum
		131	of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd).
		132	If reply is generated for master or root command (which do not have
		133	w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg
		134	structires.
		135
		136	w1_netlink_msg.status field will carry positive error value
		137	(EINVAL for example) or zero in case of success.
		138
		139	All other fields in every structure will mirror the same parameters in the
		140	request message (except lengths as described above).
		141
		142	Status reply is generated for every w1_netlink_cmd embedded in the
		143	w1_netlink_msg, if there are no w1_netlink_cmd structures,
		144	reply will be generated for the w1_netlink_msg.
		145
		146	All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
		147	even if there were errors, only length mismatch interrupts message processing.
		148
62		149
63	Operation steps in w1 core when new command is received.	150	Operation steps in w1 core when new command is received.
64	=======================================================	151	=======================================================
65		152
66	When new message (w1_netlink_msg) is received w1 core detects if it is master of slave request,	153	When new message (w1_netlink_msg) is received w1 core detects if it is
67	according to w1_netlink_msg.type field.	154	master or slave request, according to w1_netlink_msg.type field.
68	Then master or slave device is searched for.	155	Then master or slave device is searched for.
69	When found, master device (requested or those one on where slave device is found) is locked.	156	When found, master device (requested or those one on where slave device
70	If slave command is requested, then reset/select procedure is started to select given device.	157	is found) is locked. If slave command is requested, then reset/select
		158	procedure is started to select given device.
71		159
72	Then all requested in w1_netlink_msg operations are performed one by one.	160	Then all requested in w1_netlink_msg operations are performed one by one.
73	If command requires reply (like read command) it is sent on command completion.	161	If command requires reply (like read command) it is sent on command completion.
@@ -82,8 +170,8 @@ Connector [1] specific documentation.
82	Each connector message includes two u32 fields as "address".	170	Each connector message includes two u32 fields as "address".
83	w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.	171	w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
84	Each message also includes sequence and acknowledge numbers.	172	Each message also includes sequence and acknowledge numbers.
85	Sequence number for event messages is appropriate bus master sequence number increased with	173	Sequence number for event messages is appropriate bus master sequence number
86	each event message sent "through" this master.	174	increased with each event message sent "through" this master.
87	Sequence number for userspace requests is set by userspace application.	175	Sequence number for userspace requests is set by userspace application.
88	Sequence number for reply is the same as was in request, and	176	Sequence number for reply is the same as was in request, and
89	acknowledge number is set to seq+1.	177	acknowledge number is set to seq+1.
@@ -93,6 +181,6 @@ Additional documantion, source code examples.
93	============================================	181	============================================
94		182
95	1. Documentation/connector	183	1. Documentation/connector
96	2. http://tservice.net.ru/~s0mbre/archive/w1	184	2. http://www.ioremap.net/archive/w1
97	This archive includes userspace application w1d.c which	185	This archive includes userspace application w1d.c which uses
98	uses read/write/search commands for all master/slave devices found on the bus.	186	read/write/search commands for all master/slave devices found on the bus.