w1: documentation update
[linux-2.6.git] / Documentation / w1 / w1.netlink
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 Operation steps in w1 core when new command is received.
116 =======================================================
117
118 When new message (w1_netlink_msg) is received w1 core detects if it is
119 master or slave request, according to w1_netlink_msg.type field.
120 Then master or slave device is searched for.
121 When found, master device (requested or those one on where slave device
122 is found) is locked. If slave command is requested, then reset/select
123 procedure is started to select given device.
124
125 Then all requested in w1_netlink_msg operations are performed one by one.
126 If command requires reply (like read command) it is sent on command completion.
127
128 When all commands (w1_netlink_cmd) are processed muster device is unlocked
129 and next w1_netlink_msg header processing started.
130
131
132 Connector [1] specific documentation.
133 ====================================
134
135 Each connector message includes two u32 fields as "address".
136 w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
137 Each message also includes sequence and acknowledge numbers.
138 Sequence number for event messages is appropriate bus master sequence number
139 increased with each event message sent "through" this master.
140 Sequence number for userspace requests is set by userspace application.
141 Sequence number for reply is the same as was in request, and
142 acknowledge number is set to seq+1.
143
144
145 Additional documantion, source code examples.
146 ============================================
147
148 1. Documentation/connector
149 2. http://www.ioremap.net/archive/w1
150 This archive includes userspace application w1d.c which uses
151 read/write/search commands for all master/slave devices found on the bus.