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