1=============================================== 2Userspace communication protocol over connector 3=============================================== 4 5Message types 6============= 7 8There are three types of messages between w1 core and userspace: 9 101. Events. They are generated each time a new master or slave device 11 is found either due to automatic or requested search. 122. Userspace commands. 133. Replies to userspace commands. 14 15 16Protocol 17======== 18 19:: 20 21 [struct cn_msg] - connector header. 22 Its length field is equal to size of the attached data 23 [struct w1_netlink_msg] - w1 netlink header. 24 __u8 type - message type. 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) 37 __u8 status - error indication from kernel 38 __u16 len - size of data attached to this header data 39 union { 40 __u8 id[8]; - slave unique device id 41 struct w1_mst { 42 __u32 id; - master's id 43 __u32 res; - reserved 44 } mst; 45 } id; 46 47 [struct w1_netlink_cmd] - command for given master or slave device. 48 __u8 cmd - command opcode. 49 W1_CMD_READ - read command 50 W1_CMD_WRITE - write command 51 W1_CMD_SEARCH - search command 52 W1_CMD_ALARM_SEARCH - alarm search command 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 59 __u8 res - reserved 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 63 64 65Each connector message can include one or more w1_netlink_msg with 66zero or more attached w1_netlink_cmd messages. 67 68For event messages there are no w1_netlink_cmd embedded structures, 69only connector header and w1_netlink_msg structure 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. 74 75Currently 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 78messages looks like the following:: 79 80 [cn_msg][w1_netlink_msg][w1_netlink_cmd] 81 cn_msg.len = sizeof(struct w1_netlink_msg) + 82 sizeof(struct w1_netlink_cmd) + 83 cmd->len; 84 w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; 85 w1_netlink_cmd.len = cmd->len; 86 87Replies to W1_LIST_MASTERS should send a message back to the userspace 88which will contain list of all registered master ids in the following 89format:: 90 91 cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct 92 w1_netlink_msg) plus number of masters multiplied by 4) 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 97Each message is at most 4k in size, so if number of master devices 98exceeds this, it will be split into several messages. 99 100W1 search and alarm search commands. 101 102request:: 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 111 [cn_msg, ack = 1 and increasing, 0 means the last message, 112 seq is equal to the request seq] 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] 117 118Length 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. 120Can 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) + 126 sizeof(struct w1_netlink_cmd) + 127 N*8; 128 129W1 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] 135 136 137Command status replies 138====================== 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 149structures. 150 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 165Operation steps in w1 core when new command is received 166======================================================= 167 168When new message (w1_netlink_msg) is received w1 core detects if it is 169master or slave request, according to w1_netlink_msg.type field. 170Then master or slave device is searched for. 171When 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. 174 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 178When all commands (w1_netlink_cmd) are processed master device is unlocked 179and next w1_netlink_msg header processing started. 180 181 182Connector [1] specific documentation 183==================================== 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. 188Sequence number for event messages is appropriate bus master sequence number 189increased with each event message sent "through" this master. 190Sequence 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 195Additional documentation, source code examples 196============================================== 197 1981. Documentation/driver-api/connector.rst 1992. http://www.ioremap.net/archive/w1 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. 203