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