Commit | Line | Data |
---|---|---|
12003375 EP |
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 found | |
9 | either due to automatic or requested search. | |
10 | 2. Userspace commands. Includes read/write and search/alarm search comamnds. | |
11 | 3. Replies to userspace commands. | |
12 | ||
13 | ||
14 | Protocol. | |
15 | ======== | |
16 | ||
17 | [struct cn_msg] - connector header. It's length field is equal to size of the attached data. | |
18 | [struct w1_netlink_msg] - w1 netlink header. | |
19 | __u8 type - message type. | |
20 | W1_SLAVE_ADD/W1_SLAVE_REMOVE - slave add/remove events. | |
21 | W1_MASTER_ADD/W1_MASTER_REMOVE - master add/remove events. | |
22 | W1_MASTER_CMD - userspace command for bus master device (search/alarm search). | |
23 | W1_SLAVE_CMD - userspace command for slave device (read/write/ search/alarm search | |
24 | for bus master device where given slave device found). | |
25 | __u8 res - reserved | |
26 | __u16 len - size of attached to this header data. | |
27 | union { | |
28 | __u8 id; - slave unique device id | |
29 | struct w1_mst { | |
30 | __u32 id; - master's id. | |
31 | __u32 res; - reserved | |
32 | } mst; | |
33 | } id; | |
34 | ||
35 | [strucrt w1_netlink_cmd] - command for gived master or slave device. | |
36 | __u8 cmd - command opcode. | |
37 | W1_CMD_READ - read command. | |
38 | W1_CMD_WRITE - write command. | |
39 | W1_CMD_SEARCH - search command. | |
40 | W1_CMD_ALARM_SEARCH - alarm search command. | |
41 | __u8 res - reserved | |
42 | __u16 len - length of data for this command. | |
43 | For read command data must be allocated like for write command. | |
44 | __u8 data[0] - data for this command. | |
45 | ||
46 | ||
47 | Each connector message can include one or more w1_netlink_msg with zero of more attached w1_netlink_cmd messages. | |
48 | ||
49 | For event messages there are no w1_netlink_cmd embedded structures, only connector header | |
50 | and w1_netlink_msg strucutre with "len" field being zero and filled type (one of event types) | |
51 | and id - either 8 bytes of slave unique id in host order, or master's id, which is assigned | |
52 | to bus master device when it is added to w1 core. | |
53 | ||
54 | Currently replies to userspace commands are only generated for read command request. | |
55 | One reply is generated exactly for one w1_netlink_cmd read request. | |
56 | Replies are not combined when sent - i.e. typical reply messages looks like the following: | |
57 | [cn_msg][w1_netlink_msg][w1_netlink_cmd] | |
58 | cn_msg.len = sizeof(struct w1_netlink_msg) + sizeof(struct w1_netlink_cmd) + cmd->len; | |
59 | w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; | |
60 | w1_netlink_cmd.len = cmd->len; | |
61 | ||
62 | ||
63 | Operation steps in w1 core when new command is received. | |
64 | ======================================================= | |
65 | ||
66 | When new message (w1_netlink_msg) is received w1 core detects if it is master of slave request, | |
67 | according to w1_netlink_msg.type field. | |
68 | Then master or slave device is searched for. | |
69 | When found, master device (requested or those one on where slave device is found) is locked. | |
70 | If slave command is requested, then reset/select procedure is started to select given device. | |
71 | ||
72 | Then all requested in w1_netlink_msg operations are performed one by one. | |
73 | If command requires reply (like read command) it is sent on command completion. | |
74 | ||
75 | When all commands (w1_netlink_cmd) are processed muster device is unlocked | |
76 | and next w1_netlink_msg header processing started. | |
77 | ||
78 | ||
79 | Connector [1] specific documentation. | |
80 | ==================================== | |
81 | ||
82 | Each connector message includes two u32 fields as "address". | |
83 | w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header. | |
84 | Each message also includes sequence and acknowledge numbers. | |
85 | Sequence number for event messages is appropriate bus master sequence number increased with | |
86 | each event message sent "through" this master. | |
87 | Sequence number for userspace requests is set by userspace application. | |
88 | Sequence number for reply is the same as was in request, and | |
89 | acknowledge number is set to seq+1. | |
90 | ||
91 | ||
92 | Additional documantion, source code examples. | |
93 | ============================================ | |
94 | ||
95 | 1. Documentation/connector | |
96 | 2. http://tservice.net.ru/~s0mbre/archive/w1 | |
97 | This archive includes userspace application w1d.c which | |
98 | uses read/write/search commands for all master/slave devices found on the bus. |