blob: aaa13243a5e43ddbacc9a7c42afa67e4bcb985d4 [file] [log] [blame]
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -03001===============================================
2Userspace communication protocol over connector
3===============================================
Evgeniy Polyakov12003372006-03-23 19:11:58 +03004
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -03005Message types
Evgeniy Polyakov12003372006-03-23 19:11:58 +03006=============
7
8There are three types of messages between w1 core and userspace:
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -03009
David Friesb3be1772014-01-15 22:29:25 -0600101. Events. They are generated each time a new master or slave device
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -030011 is found either due to automatic or requested search.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800122. Userspace commands.
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300133. Replies to userspace commands.
14
15
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -030016Protocol
Evgeniy Polyakov12003372006-03-23 19:11:58 +030017========
18
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -030019::
20
21 [struct cn_msg] - connector header.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080022 Its length field is equal to size of the attached data
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -030023 [struct w1_netlink_msg] - w1 netlink header.
Evgeniy Polyakov12003372006-03-23 19:11:58 +030024 __u8 type - message type.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080025 W1_LIST_MASTERS
26 list current bus masters
27 W1_SLAVE_ADD/W1_SLAVE_REMOVE
28 slave add/remove events
29 W1_MASTER_ADD/W1_MASTER_REMOVE
30 master add/remove events
31 W1_MASTER_CMD
32 userspace command for bus master
33 device (search/alarm search)
34 W1_SLAVE_CMD
35 userspace command for slave device
36 (read/write/touch)
David Fries8a0427d2014-04-08 22:37:09 -050037 __u8 status - error indication from kernel
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080038 __u16 len - size of data attached to this header data
Evgeniy Polyakov12003372006-03-23 19:11:58 +030039 union {
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080040 __u8 id[8]; - slave unique device id
Evgeniy Polyakov12003372006-03-23 19:11:58 +030041 struct w1_mst {
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080042 __u32 id; - master's id
Evgeniy Polyakov12003372006-03-23 19:11:58 +030043 __u32 res; - reserved
44 } mst;
45 } id;
46
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -030047 [struct w1_netlink_cmd] - command for given master or slave device.
Evgeniy Polyakov12003372006-03-23 19:11:58 +030048 __u8 cmd - command opcode.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080049 W1_CMD_READ - read command
50 W1_CMD_WRITE - write command
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080051 W1_CMD_SEARCH - search command
52 W1_CMD_ALARM_SEARCH - alarm search command
David Fries8a0427d2014-04-08 22:37:09 -050053 W1_CMD_TOUCH - touch command
54 (write and sample data back to userspace)
55 W1_CMD_RESET - send bus reset
56 W1_CMD_SLAVE_ADD - add slave to kernel list
57 W1_CMD_SLAVE_REMOVE - remove slave from kernel list
58 W1_CMD_LIST_SLAVES - get slaves list from kernel
Evgeniy Polyakov12003372006-03-23 19:11:58 +030059 __u8 res - reserved
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080060 __u16 len - length of data for this command
61 For read command data must be allocated like for write command
62 __u8 data[0] - data for this command
Evgeniy Polyakov12003372006-03-23 19:11:58 +030063
64
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080065Each connector message can include one or more w1_netlink_msg with
66zero or more attached w1_netlink_cmd messages.
Evgeniy Polyakov12003372006-03-23 19:11:58 +030067
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080068For event messages there are no w1_netlink_cmd embedded structures,
69only connector header and w1_netlink_msg strucutre with "len" field
70being zero and filled type (one of event types) and id:
71either 8 bytes of slave unique id in host order,
72or master's id, which is assigned to bus master device
73when it is added to w1 core.
Evgeniy Polyakov12003372006-03-23 19:11:58 +030074
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080075Currently replies to userspace commands are only generated for read
76command request. One reply is generated exactly for one w1_netlink_cmd
77read request. Replies are not combined when sent - i.e. typical reply
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -030078messages looks like the following::
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080079
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -030080 [cn_msg][w1_netlink_msg][w1_netlink_cmd]
81 cn_msg.len = sizeof(struct w1_netlink_msg) +
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080082 sizeof(struct w1_netlink_cmd) +
83 cmd->len;
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -030084 w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
85 w1_netlink_cmd.len = cmd->len;
Evgeniy Polyakov12003372006-03-23 19:11:58 +030086
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080087Replies to W1_LIST_MASTERS should send a message back to the userspace
88which will contain list of all registered master ids in the following
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -030089format::
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080090
91 cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
Lucas De Marchi25985ed2011-03-30 22:57:33 -030092 w1_netlink_msg) plus number of masters multiplied by 4)
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080093 w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to
94 number of masters multiplied by 4 (u32 size))
95 id0 ... idN
96
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -030097Each message is at most 4k in size, so if number of master devices
98exceeds this, it will be split into several messages.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -080099
100W1 search and alarm search commands.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800101
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -0300102request::
103
104 [cn_msg]
105 [w1_netlink_msg type = W1_MASTER_CMD
106 id is equal to the bus master id to use for searching]
107 [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
108
109reply::
110
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800111 [cn_msg, ack = 1 and increasing, 0 means the last message,
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -0300112 seq is equal to the request seq]
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800113 [w1_netlink_msg type = W1_MASTER_CMD]
114 [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
115 len is equal to number of IDs multiplied by 8]
116 [64bit-id0 ... 64bit-idN]
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -0300117
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800118Length in each header corresponds to the size of the data behind it, so
119w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -0300120Can be zero.
121
122::
123
124 w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
125 cn_msg->len = sizeof(struct w1_netlink_msg) +
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800126 sizeof(struct w1_netlink_cmd) +
127 N*8;
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300128
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -0300129W1 reset command::
130
131 [cn_msg]
132 [w1_netlink_msg type = W1_MASTER_CMD
133 id is equal to the bus master id to use for searching]
134 [w1_netlink_cmd cmd = W1_CMD_RESET]
Evgeniy Polyakovf89735c2009-01-07 18:09:04 -0800135
Evgeniy Polyakov40370142009-01-07 18:09:05 -0800136
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -0300137Command status replies
Evgeniy Polyakov40370142009-01-07 18:09:05 -0800138======================
139
140Each command (either root, master or slave with or without w1_netlink_cmd
141structure) will be 'acked' by the w1 core. Format of the reply is the same
142as request message except that length parameters do not account for data
143requested by the user, i.e. read/write/touch IO requests will not contain
144data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size
145of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum
146of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd).
147If reply is generated for master or root command (which do not have
148w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg
David Friesb3be1772014-01-15 22:29:25 -0600149structures.
Evgeniy Polyakov40370142009-01-07 18:09:05 -0800150
151w1_netlink_msg.status field will carry positive error value
152(EINVAL for example) or zero in case of success.
153
154All other fields in every structure will mirror the same parameters in the
155request message (except lengths as described above).
156
157Status reply is generated for every w1_netlink_cmd embedded in the
158w1_netlink_msg, if there are no w1_netlink_cmd structures,
159reply will be generated for the w1_netlink_msg.
160
161All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
162even if there were errors, only length mismatch interrupts message processing.
163
164
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -0300165Operation steps in w1 core when new command is received
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300166=======================================================
167
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800168When new message (w1_netlink_msg) is received w1 core detects if it is
169master or slave request, according to w1_netlink_msg.type field.
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300170Then master or slave device is searched for.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800171When found, master device (requested or those one on where slave device
172is found) is locked. If slave command is requested, then reset/select
173procedure is started to select given device.
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300174
175Then all requested in w1_netlink_msg operations are performed one by one.
176If command requires reply (like read command) it is sent on command completion.
177
David Friesb3be1772014-01-15 22:29:25 -0600178When all commands (w1_netlink_cmd) are processed master device is unlocked
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300179and next w1_netlink_msg header processing started.
180
181
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -0300182Connector [1] specific documentation
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300183====================================
184
185Each connector message includes two u32 fields as "address".
186w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
187Each message also includes sequence and acknowledge numbers.
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -0800188Sequence number for event messages is appropriate bus master sequence number
189increased with each event message sent "through" this master.
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300190Sequence number for userspace requests is set by userspace application.
191Sequence number for reply is the same as was in request, and
192acknowledge number is set to seq+1.
193
194
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -0300195Additional documentation, source code examples
196==============================================
Evgeniy Polyakov12003372006-03-23 19:11:58 +0300197
Mauro Carvalho Chehabbaa293e2019-06-27 15:39:22 -03001981. Documentation/driver-api/connector.rst
Evgeniy Polyakove4e056a2009-01-07 18:09:02 -08001992. http://www.ioremap.net/archive/w1
Mauro Carvalho Chehabe9bb6272019-07-31 17:08:53 -0300200
201 This archive includes userspace application w1d.c which uses
202 read/write/search commands for all master/slave devices found on the bus.