1 ==============================================
2 Userspace communication protocol over connecto
3 ==============================================
4
5 Message types
6 =============
7
8 There are three types of messages between w1 c
9
10 1. Events. They are generated each time a new
11 is found either due to automatic or request
12 2. Userspace commands.
13 3. Replies to userspace commands.
14
15
16 Protocol
17 ========
18
19 ::
20
21 [struct cn_msg] - connector header.
22 Its length field is equal to size of t
23 [struct w1_netlink_msg] - w1 netlink header.
24 __u8 type - message type.
25 W1_LIST_MASTERS
26 list current b
27 W1_SLAVE_ADD/W1_SLAVE_
28 slave add/remo
29 W1_MASTER_ADD/W1_MASTE
30 master add/rem
31 W1_MASTER_CMD
32 userspace comm
33 device (search
34 W1_SLAVE_CMD
35 userspace comm
36 (read/write/to
37 __u8 status - error indication fro
38 __u16 len - size of data attache
39 union {
40 __u8 id[8];
41 struct w1_mst {
42 __u32 id;
43 __u32 res;
44 } mst;
45 } id;
46
47 [struct w1_netlink_cmd] - command for given
48 __u8 cmd - command opcode.
49 W1_CMD_READ - read
50 W1_CMD_WRITE - writ
51 W1_CMD_SEARCH - sear
52 W1_CMD_ALARM_SEARCH -
53 W1_CMD_TOUCH - touc
54 (write and sam
55 W1_CMD_RESET - send
56 W1_CMD_SLAVE_ADD
57 W1_CMD_SLAVE_REMOVE
58 W1_CMD_LIST_SLAVES
59 __u8 res - reserved
60 __u16 len - length of data for t
61 For read command data must be
62 __u8 data[0] - data for this comman
63
64
65 Each connector message can include one or more
66 zero or more attached w1_netlink_cmd messages.
67
68 For event messages there are no w1_netlink_cmd
69 only connector header and w1_netlink_msg struc
70 being zero and filled type (one of event types
71 either 8 bytes of slave unique id in host orde
72 or master's id, which is assigned to bus maste
73 when it is added to w1 core.
74
75 Currently replies to userspace commands are on
76 command request. One reply is generated exactl
77 read request. Replies are not combined when se
78 messages looks like the following::
79
80 [cn_msg][w1_netlink_msg][w1_netlink_cmd]
81 cn_msg.len = sizeof(struct w1_netlink_msg) +
82 sizeof(struct w1_netlink_cmd) +
83 cmd->len;
84 w1_netlink_msg.len = sizeof(struct w1_netlin
85 w1_netlink_cmd.len = cmd->len;
86
87 Replies to W1_LIST_MASTERS should send a messa
88 which will contain list of all registered mast
89 format::
90
91 cn_msg (CN_W1_IDX.CN_W1_VAL as id, len
92 w1_netlink_msg) plus number of masters
93 w1_netlink_msg (type: W1_LIST_MASTERS,
94 number of masters multiplied b
95 id0 ... idN
96
97 Each message is at most 4k in size, so if numb
98 exceeds this, it will be split into several me
99
100 W1 search and alarm search commands.
101
102 request::
103
104 [cn_msg]
105 [w1_netlink_msg type = W1_MASTER_CMD
106 id is equal to the bus master id to us
107 [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_
108
109 reply::
110
111 [cn_msg, ack = 1 and increasing, 0 means the
112 seq is equal to the request seq]
113 [w1_netlink_msg type = W1_MASTER_CMD]
114 [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CM
115 len is equal to number of IDs multipli
116 [64bit-id0 ... 64bit-idN]
117
118 Length in each header corresponds to the size
119 w1_netlink_cmd->len = N * 8; where N is number
120 Can be zero.
121
122 ::
123
124 w1_netlink_msg->len = sizeof(struct w1_netli
125 cn_msg->len = sizeof(struct w1_netlink_msg)
126 sizeof(struct w1_netlink_cmd) +
127 N*8;
128
129 W1 reset command::
130
131 [cn_msg]
132 [w1_netlink_msg type = W1_MASTER_CMD
133 id is equal to the bus master id to us
134 [w1_netlink_cmd cmd = W1_CMD_RESET]
135
136
137 Command status replies
138 ======================
139
140 Each command (either root, master or slave wit
141 structure) will be 'acked' by the w1 core. For
142 as request message except that length paramete
143 requested by the user, i.e. read/write/touch I
144 data, so w1_netlink_cmd.len will be 0, w1_netl
145 of the w1_netlink_cmd structure and cn_msg.len
146 of the sizeof(struct w1_netlink_msg) and sizeo
147 If reply is generated for master or root comma
148 w1_netlink_cmd attached), reply will contain o
149 structures.
150
151 w1_netlink_msg.status field will carry positiv
152 (EINVAL for example) or zero in case of succes
153
154 All other fields in every structure will mirro
155 request message (except lengths as described a
156
157 Status reply is generated for every w1_netlink
158 w1_netlink_msg, if there are no w1_netlink_cmd
159 reply will be generated for the w1_netlink_msg
160
161 All w1_netlink_cmd command structures are hand
162 even if there were errors, only length mismatc
163
164
165 Operation steps in w1 core when new command is
166 ==============================================
167
168 When new message (w1_netlink_msg) is received
169 master or slave request, according to w1_netli
170 Then master or slave device is searched for.
171 When found, master device (requested or those
172 is found) is locked. If slave command is reque
173 procedure is started to select given device.
174
175 Then all requested in w1_netlink_msg operation
176 If command requires reply (like read command)
177
178 When all commands (w1_netlink_cmd) are process
179 and next w1_netlink_msg header processing star
180
181
182 Connector [1] specific documentation
183 ====================================
184
185 Each connector message includes two u32 fields
186 w1 uses CN_W1_IDX and CN_W1_VAL defined in inc
187 Each message also includes sequence and acknow
188 Sequence number for event messages is appropri
189 increased with each event message sent "throug
190 Sequence number for userspace requests is set
191 Sequence number for reply is the same as was i
192 acknowledge number is set to seq+1.
193
194
195 Additional documentation, source code examples
196 ==============================================
197
198 1. Documentation/driver-api/connector.rst
199 2. http://www.ioremap.net/archive/w1
200
201 This archive includes userspace application
202 read/write/search commands for all master/s
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.