blob: d596d406e0a5386fb360921245554d4bc2c8bccd [file] [log] [blame]
Evgeniy Polyakov12003372006-03-23 19:11:58 +03001Userspace communication protocol over connector [1].
2
3
4Message types.
5=============
6
7There are three types of messages between w1 core and userspace:
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080081. Events. They are generated each time new master or slave device
9 found either due to automatic or requested search.
102. Userspace commands.
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300113. Replies to userspace commands.
12
13
14Protocol.
15========
16
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080017[struct cn_msg] - connector header.
18 Its length field is equal to size of the attached data
Evgeniy Polyakov12003372006-03-23 19:11:58 +030019[struct w1_netlink_msg] - w1 netlink header.
20 __u8 type - message type.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080021 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)
Evgeniy Polyakov12003372006-03-23 19:11:58 +030033 __u8 res - reserved
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080034 __u16 len - size of data attached to this header data
Evgeniy Polyakov12003372006-03-23 19:11:58 +030035 union {
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080036 __u8 id[8]; - slave unique device id
Evgeniy Polyakov12003372006-03-23 19:11:58 +030037 struct w1_mst {
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080038 __u32 id; - master's id
Evgeniy Polyakov12003372006-03-23 19:11:58 +030039 __u32 res; - reserved
40 } mst;
41 } id;
42
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080043[struct w1_netlink_cmd] - command for given master or slave device.
Evgeniy Polyakov12003372006-03-23 19:11:58 +030044 __u8 cmd - command opcode.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080045 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
Evgeniy Polyakov12003372006-03-23 19:11:58 +030051 __u8 res - reserved
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080052 __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
Evgeniy Polyakov12003372006-03-23 19:11:58 +030055
56
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080057Each connector message can include one or more w1_netlink_msg with
58zero or more attached w1_netlink_cmd messages.
Evgeniy Polyakov12003372006-03-23 19:11:58 +030059
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080060For event messages there are no w1_netlink_cmd embedded structures,
61only connector header and w1_netlink_msg strucutre with "len" field
62being zero and filled type (one of event types) and id:
63either 8 bytes of slave unique id in host order,
64or master's id, which is assigned to bus master device
65when it is added to w1 core.
Evgeniy Polyakov12003372006-03-23 19:11:58 +030066
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080067Currently replies to userspace commands are only generated for read
68command request. One reply is generated exactly for one w1_netlink_cmd
69read request. Replies are not combined when sent - i.e. typical reply
70messages looks like the following:
71
Evgeniy Polyakov12003372006-03-23 19:11:58 +030072[cn_msg][w1_netlink_msg][w1_netlink_cmd]
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080073cn_msg.len = sizeof(struct w1_netlink_msg) +
74 sizeof(struct w1_netlink_cmd) +
75 cmd->len;
Evgeniy Polyakov12003372006-03-23 19:11:58 +030076w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
77w1_netlink_cmd.len = cmd->len;
78
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080079Replies to W1_LIST_MASTERS should send a message back to the userspace
80which will contain list of all registered master ids in the following
81format:
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
93W1 search and alarm search commands.
94request:
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
100reply:
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]
107Length in each header corresponds to the size of the data behind it, so
108w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
109 Can be zero.
110w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
111cn_msg->len = sizeof(struct w1_netlink_msg) +
112 sizeof(struct w1_netlink_cmd) +
113 N*8;
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300114
115Operation steps in w1 core when new command is received.
116=======================================================
117
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800118When new message (w1_netlink_msg) is received w1 core detects if it is
119master or slave request, according to w1_netlink_msg.type field.
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300120Then master or slave device is searched for.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800121When found, master device (requested or those one on where slave device
122is found) is locked. If slave command is requested, then reset/select
123procedure is started to select given device.
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300124
125Then all requested in w1_netlink_msg operations are performed one by one.
126If command requires reply (like read command) it is sent on command completion.
127
128When all commands (w1_netlink_cmd) are processed muster device is unlocked
129and next w1_netlink_msg header processing started.
130
131
132Connector [1] specific documentation.
133====================================
134
135Each connector message includes two u32 fields as "address".
136w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
137Each message also includes sequence and acknowledge numbers.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800138Sequence number for event messages is appropriate bus master sequence number
139increased with each event message sent "through" this master.
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300140Sequence number for userspace requests is set by userspace application.
141Sequence number for reply is the same as was in request, and
142acknowledge number is set to seq+1.
143
144
145Additional documantion, source code examples.
146============================================
147
1481. Documentation/connector
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -08001492. http://www.ioremap.net/archive/w1
150This archive includes userspace application w1d.c which uses
151read/write/search commands for all master/slave devices found on the bus.