Commit | Line | Data |
---|---|---|
e9bb6275 MCC |
1 | =============================================== |
2 | Userspace communication protocol over connector | |
3 | =============================================== | |
12003375 | 4 | |
e9bb6275 | 5 | Message types |
12003375 EP |
6 | ============= |
7 | ||
8 | There are three types of messages between w1 core and userspace: | |
e9bb6275 | 9 | |
b3be177a | 10 | 1. Events. They are generated each time a new master or slave device |
e9bb6275 | 11 | is found either due to automatic or requested search. |
e4e056aa | 12 | 2. Userspace commands. |
12003375 EP |
13 | 3. Replies to userspace commands. |
14 | ||
15 | ||
e9bb6275 | 16 | Protocol |
12003375 EP |
17 | ======== |
18 | ||
e9bb6275 MCC |
19 | :: |
20 | ||
21 | [struct cn_msg] - connector header. | |
e4e056aa | 22 | Its length field is equal to size of the attached data |
e9bb6275 | 23 | [struct w1_netlink_msg] - w1 netlink header. |
12003375 | 24 | __u8 type - message type. |
e4e056aa EP |
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) | |
8a0427d1 | 37 | __u8 status - error indication from kernel |
e4e056aa | 38 | __u16 len - size of data attached to this header data |
12003375 | 39 | union { |
e4e056aa | 40 | __u8 id[8]; - slave unique device id |
12003375 | 41 | struct w1_mst { |
e4e056aa | 42 | __u32 id; - master's id |
12003375 EP |
43 | __u32 res; - reserved |
44 | } mst; | |
45 | } id; | |
46 | ||
e9bb6275 | 47 | [struct w1_netlink_cmd] - command for given master or slave device. |
12003375 | 48 | __u8 cmd - command opcode. |
e4e056aa EP |
49 | W1_CMD_READ - read command |
50 | W1_CMD_WRITE - write command | |
e4e056aa EP |
51 | W1_CMD_SEARCH - search command |
52 | W1_CMD_ALARM_SEARCH - alarm search command | |
8a0427d1 DF |
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 | |
12003375 | 59 | __u8 res - reserved |
e4e056aa EP |
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 | |
12003375 EP |
63 | |
64 | ||
e4e056aa EP |
65 | Each connector message can include one or more w1_netlink_msg with |
66 | zero or more attached w1_netlink_cmd messages. | |
12003375 | 67 | |
e4e056aa | 68 | For event messages there are no w1_netlink_cmd embedded structures, |
d56b699d | 69 | only connector header and w1_netlink_msg structure with "len" field |
e4e056aa EP |
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 | |
e9bb6275 | 78 | messages looks like the following:: |
12003375 | 79 | |
e9bb6275 MCC |
80 | [cn_msg][w1_netlink_msg][w1_netlink_cmd] |
81 | cn_msg.len = sizeof(struct w1_netlink_msg) + | |
e4e056aa EP |
82 | sizeof(struct w1_netlink_cmd) + |
83 | cmd->len; | |
e9bb6275 MCC |
84 | w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; |
85 | w1_netlink_cmd.len = cmd->len; | |
12003375 | 86 | |
e4e056aa EP |
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 | |
e9bb6275 | 89 | format:: |
e4e056aa EP |
90 | |
91 | cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct | |
25985edc | 92 | w1_netlink_msg) plus number of masters multiplied by 4) |
e4e056aa EP |
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 | ||
e9bb6275 MCC |
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. | |
e4e056aa EP |
99 | |
100 | W1 search and alarm search commands. | |
e4e056aa | 101 | |
e9bb6275 MCC |
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 | ||
e4e056aa | 111 | [cn_msg, ack = 1 and increasing, 0 means the last message, |
e9bb6275 | 112 | seq is equal to the request seq] |
e4e056aa EP |
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] | |
e9bb6275 | 117 | |
e4e056aa EP |
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. | |
e9bb6275 MCC |
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) + | |
e4e056aa EP |
126 | sizeof(struct w1_netlink_cmd) + |
127 | N*8; | |
12003375 | 128 | |
e9bb6275 | 129 | W1 reset command:: |
f89735c4 | 130 | |
e9bb6275 MCC |
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] | |
4037014e | 135 | |
e9bb6275 MCC |
136 | |
137 | Command status replies | |
4037014e EP |
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 | |
b3be177a | 149 | structures. |
4037014e EP |
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 | ||
e9bb6275 | 165 | Operation steps in w1 core when new command is received |
12003375 EP |
166 | ======================================================= |
167 | ||
e4e056aa EP |
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. | |
12003375 | 170 | Then master or slave device is searched for. |
e4e056aa EP |
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. | |
12003375 EP |
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 | ||
b3be177a | 178 | When all commands (w1_netlink_cmd) are processed master device is unlocked |
12003375 EP |
179 | and next w1_netlink_msg header processing started. |
180 | ||
181 | ||
e9bb6275 | 182 | Connector [1] specific documentation |
12003375 EP |
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. | |
e4e056aa EP |
188 | Sequence number for event messages is appropriate bus master sequence number |
189 | increased with each event message sent "through" this master. | |
12003375 EP |
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 | ||
e9bb6275 MCC |
195 | Additional documentation, source code examples |
196 | ============================================== | |
12003375 | 197 | |
baa293e9 | 198 | 1. Documentation/driver-api/connector.rst |
e4e056aa | 199 | 2. http://www.ioremap.net/archive/w1 |
e9bb6275 MCC |
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. |