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