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