Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 1 | =============================================== |
| 2 | Userspace communication protocol over connector |
| 3 | =============================================== |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 4 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 5 | Message types |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 6 | ============= |
| 7 | |
| 8 | There are three types of messages between w1 core and userspace: |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 9 | |
David Fries | b3be177 | 2014-01-15 22:29:25 -0600 | [diff] [blame] | 10 | 1. Events. They are generated each time a new master or slave device |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 11 | is found either due to automatic or requested search. |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 12 | 2. Userspace commands. |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 13 | 3. Replies to userspace commands. |
| 14 | |
| 15 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 16 | Protocol |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 17 | ======== |
| 18 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 19 | :: |
| 20 | |
| 21 | [struct cn_msg] - connector header. |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 22 | Its length field is equal to size of the attached data |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 23 | [struct w1_netlink_msg] - w1 netlink header. |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 24 | __u8 type - message type. |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 25 | 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 Fries | 8a0427d | 2014-04-08 22:37:09 -0500 | [diff] [blame] | 37 | __u8 status - error indication from kernel |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 38 | __u16 len - size of data attached to this header data |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 39 | union { |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 40 | __u8 id[8]; - slave unique device id |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 41 | struct w1_mst { |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 42 | __u32 id; - master's id |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 43 | __u32 res; - reserved |
| 44 | } mst; |
| 45 | } id; |
| 46 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 47 | [struct w1_netlink_cmd] - command for given master or slave device. |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 48 | __u8 cmd - command opcode. |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 49 | W1_CMD_READ - read command |
| 50 | W1_CMD_WRITE - write command |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 51 | W1_CMD_SEARCH - search command |
| 52 | W1_CMD_ALARM_SEARCH - alarm search command |
David Fries | 8a0427d | 2014-04-08 22:37:09 -0500 | [diff] [blame] | 53 | 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 Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 59 | __u8 res - reserved |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 60 | __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 Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 63 | |
| 64 | |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 65 | Each connector message can include one or more w1_netlink_msg with |
| 66 | zero or more attached w1_netlink_cmd messages. |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 67 | |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 68 | For event messages there are no w1_netlink_cmd embedded structures, |
| 69 | only connector header and w1_netlink_msg strucutre with "len" field |
| 70 | being zero and filled type (one of event types) and id: |
| 71 | either 8 bytes of slave unique id in host order, |
| 72 | or master's id, which is assigned to bus master device |
| 73 | when it is added to w1 core. |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 74 | |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 75 | Currently replies to userspace commands are only generated for read |
| 76 | command request. One reply is generated exactly for one w1_netlink_cmd |
| 77 | read request. Replies are not combined when sent - i.e. typical reply |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 78 | messages looks like the following:: |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 79 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 80 | [cn_msg][w1_netlink_msg][w1_netlink_cmd] |
| 81 | cn_msg.len = sizeof(struct w1_netlink_msg) + |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 82 | sizeof(struct w1_netlink_cmd) + |
| 83 | cmd->len; |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 84 | w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; |
| 85 | w1_netlink_cmd.len = cmd->len; |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 86 | |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 87 | Replies to W1_LIST_MASTERS should send a message back to the userspace |
| 88 | which will contain list of all registered master ids in the following |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 89 | format:: |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 90 | |
| 91 | cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct |
Lucas De Marchi | 25985ed | 2011-03-30 22:57:33 -0300 | [diff] [blame] | 92 | w1_netlink_msg) plus number of masters multiplied by 4) |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 93 | 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 Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 97 | Each message is at most 4k in size, so if number of master devices |
| 98 | exceeds this, it will be split into several messages. |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 99 | |
| 100 | W1 search and alarm search commands. |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 101 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 102 | request:: |
| 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 | |
| 109 | reply:: |
| 110 | |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 111 | [cn_msg, ack = 1 and increasing, 0 means the last message, |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 112 | seq is equal to the request seq] |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 113 | [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 Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 117 | |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 118 | Length in each header corresponds to the size of the data behind it, so |
| 119 | w1_netlink_cmd->len = N * 8; where N is number of IDs in this message. |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 120 | Can 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 Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 126 | sizeof(struct w1_netlink_cmd) + |
| 127 | N*8; |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 128 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 129 | W1 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 Polyakov | f89735c | 2009-01-07 18:09:04 -0800 | [diff] [blame] | 135 | |
Evgeniy Polyakov | 4037014 | 2009-01-07 18:09:05 -0800 | [diff] [blame] | 136 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 137 | Command status replies |
Evgeniy Polyakov | 4037014 | 2009-01-07 18:09:05 -0800 | [diff] [blame] | 138 | ====================== |
| 139 | |
| 140 | Each command (either root, master or slave with or without w1_netlink_cmd |
| 141 | structure) will be 'acked' by the w1 core. Format of the reply is the same |
| 142 | as request message except that length parameters do not account for data |
| 143 | requested by the user, i.e. read/write/touch IO requests will not contain |
| 144 | data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size |
| 145 | of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum |
| 146 | of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd). |
| 147 | If reply is generated for master or root command (which do not have |
| 148 | w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg |
David Fries | b3be177 | 2014-01-15 22:29:25 -0600 | [diff] [blame] | 149 | structures. |
Evgeniy Polyakov | 4037014 | 2009-01-07 18:09:05 -0800 | [diff] [blame] | 150 | |
| 151 | w1_netlink_msg.status field will carry positive error value |
| 152 | (EINVAL for example) or zero in case of success. |
| 153 | |
| 154 | All other fields in every structure will mirror the same parameters in the |
| 155 | request message (except lengths as described above). |
| 156 | |
| 157 | Status reply is generated for every w1_netlink_cmd embedded in the |
| 158 | w1_netlink_msg, if there are no w1_netlink_cmd structures, |
| 159 | reply will be generated for the w1_netlink_msg. |
| 160 | |
| 161 | All w1_netlink_cmd command structures are handled in every w1_netlink_msg, |
| 162 | even if there were errors, only length mismatch interrupts message processing. |
| 163 | |
| 164 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 165 | Operation steps in w1 core when new command is received |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 166 | ======================================================= |
| 167 | |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 168 | When new message (w1_netlink_msg) is received w1 core detects if it is |
| 169 | master or slave request, according to w1_netlink_msg.type field. |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 170 | Then master or slave device is searched for. |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 171 | When found, master device (requested or those one on where slave device |
| 172 | is found) is locked. If slave command is requested, then reset/select |
| 173 | procedure is started to select given device. |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 174 | |
| 175 | Then all requested in w1_netlink_msg operations are performed one by one. |
| 176 | If command requires reply (like read command) it is sent on command completion. |
| 177 | |
David Fries | b3be177 | 2014-01-15 22:29:25 -0600 | [diff] [blame] | 178 | When all commands (w1_netlink_cmd) are processed master device is unlocked |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 179 | and next w1_netlink_msg header processing started. |
| 180 | |
| 181 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 182 | Connector [1] specific documentation |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 183 | ==================================== |
| 184 | |
| 185 | Each connector message includes two u32 fields as "address". |
| 186 | w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header. |
| 187 | Each message also includes sequence and acknowledge numbers. |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 188 | Sequence number for event messages is appropriate bus master sequence number |
| 189 | increased with each event message sent "through" this master. |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 190 | Sequence number for userspace requests is set by userspace application. |
| 191 | Sequence number for reply is the same as was in request, and |
| 192 | acknowledge number is set to seq+1. |
| 193 | |
| 194 | |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 195 | Additional documentation, source code examples |
| 196 | ============================================== |
Evgeniy Polyakov | 1200337 | 2006-03-23 19:11:58 +0300 | [diff] [blame] | 197 | |
Mauro Carvalho Chehab | baa293e | 2019-06-27 15:39:22 -0300 | [diff] [blame] | 198 | 1. Documentation/driver-api/connector.rst |
Evgeniy Polyakov | e4e056a | 2009-01-07 18:09:02 -0800 | [diff] [blame] | 199 | 2. http://www.ioremap.net/archive/w1 |
Mauro Carvalho Chehab | e9bb627 | 2019-07-31 17:08:53 -0300 | [diff] [blame] | 200 | |
| 201 | This archive includes userspace application w1d.c which uses |
| 202 | read/write/search commands for all master/slave devices found on the bus. |