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