Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
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 a new master or slave device 9 is 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 status - error indication from kernel 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_SEARCH - search command 48 W1_CMD_ALARM_SEARCH - alarm search command 49 W1_CMD_TOUCH - touch command 50 (write and sample data back to userspace) 51 W1_CMD_RESET - send bus reset 52 W1_CMD_SLAVE_ADD - add slave to kernel list 53 W1_CMD_SLAVE_REMOVE - remove slave from kernel list 54 W1_CMD_LIST_SLAVES - get slaves list from kernel 55 __u8 res - reserved 56 __u16 len - length of data for this command 57 For read command data must be allocated like for write command 58 __u8 data[0] - data for this command 59 60 61 Each connector message can include one or more w1_netlink_msg with 62 zero or more attached w1_netlink_cmd messages. 63 64 For event messages there are no w1_netlink_cmd embedded structures, 65 only connector header and w1_netlink_msg strucutre with "len" field 66 being zero and filled type (one of event types) and id: 67 either 8 bytes of slave unique id in host order, 68 or master's id, which is assigned to bus master device 69 when it is added to w1 core. 70 71 Currently replies to userspace commands are only generated for read 72 command request. One reply is generated exactly for one w1_netlink_cmd 73 read request. Replies are not combined when sent - i.e. typical reply 74 messages looks like the following: 75 76 [cn_msg][w1_netlink_msg][w1_netlink_cmd] 77 cn_msg.len = sizeof(struct w1_netlink_msg) + 78 sizeof(struct w1_netlink_cmd) + 79 cmd->len; 80 w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; 81 w1_netlink_cmd.len = cmd->len; 82 83 Replies to W1_LIST_MASTERS should send a message back to the userspace 84 which will contain list of all registered master ids in the following 85 format: 86 87 cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct 88 w1_netlink_msg) plus number of masters multiplied by 4) 89 w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to 90 number of masters multiplied by 4 (u32 size)) 91 id0 ... idN 92 93 Each message is at most 4k in size, so if number of master devices 94 exceeds this, it will be split into several messages. 95 96 W1 search and alarm search commands. 97 request: 98 [cn_msg] 99 [w1_netlink_msg type = W1_MASTER_CMD 100 id is equal to the bus master id to use for searching] 101 [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH] 102 103 reply: 104 [cn_msg, ack = 1 and increasing, 0 means the last message, 105 seq is equal to the request seq] 106 [w1_netlink_msg type = W1_MASTER_CMD] 107 [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH 108 len is equal to number of IDs multiplied by 8] 109 [64bit-id0 ... 64bit-idN] 110 Length in each header corresponds to the size of the data behind it, so 111 w1_netlink_cmd->len = N * 8; where N is number of IDs in this message. 112 Can be zero. 113 w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8; 114 cn_msg->len = sizeof(struct w1_netlink_msg) + 115 sizeof(struct w1_netlink_cmd) + 116 N*8; 117 118 W1 reset command. 119 [cn_msg] 120 [w1_netlink_msg type = W1_MASTER_CMD 121 id is equal to the bus master id to use for searching] 122 [w1_netlink_cmd cmd = W1_CMD_RESET] 123 124 125 Command status replies. 126 ====================== 127 128 Each command (either root, master or slave with or without w1_netlink_cmd 129 structure) will be 'acked' by the w1 core. Format of the reply is the same 130 as request message except that length parameters do not account for data 131 requested by the user, i.e. read/write/touch IO requests will not contain 132 data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size 133 of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum 134 of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd). 135 If reply is generated for master or root command (which do not have 136 w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg 137 structures. 138 139 w1_netlink_msg.status field will carry positive error value 140 (EINVAL for example) or zero in case of success. 141 142 All other fields in every structure will mirror the same parameters in the 143 request message (except lengths as described above). 144 145 Status reply is generated for every w1_netlink_cmd embedded in the 146 w1_netlink_msg, if there are no w1_netlink_cmd structures, 147 reply will be generated for the w1_netlink_msg. 148 149 All w1_netlink_cmd command structures are handled in every w1_netlink_msg, 150 even if there were errors, only length mismatch interrupts message processing. 151 152 153 Operation steps in w1 core when new command is received. 154 ======================================================= 155 156 When new message (w1_netlink_msg) is received w1 core detects if it is 157 master or slave request, according to w1_netlink_msg.type field. 158 Then master or slave device is searched for. 159 When found, master device (requested or those one on where slave device 160 is found) is locked. If slave command is requested, then reset/select 161 procedure is started to select given device. 162 163 Then all requested in w1_netlink_msg operations are performed one by one. 164 If command requires reply (like read command) it is sent on command completion. 165 166 When all commands (w1_netlink_cmd) are processed master device is unlocked 167 and next w1_netlink_msg header processing started. 168 169 170 Connector [1] specific documentation. 171 ==================================== 172 173 Each connector message includes two u32 fields as "address". 174 w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header. 175 Each message also includes sequence and acknowledge numbers. 176 Sequence number for event messages is appropriate bus master sequence number 177 increased with each event message sent "through" this master. 178 Sequence number for userspace requests is set by userspace application. 179 Sequence number for reply is the same as was in request, and 180 acknowledge number is set to seq+1. 181 182 183 Additional documantion, source code examples. 184 ============================================ 185 186 1. Documentation/connector 187 2. http://www.ioremap.net/archive/w1 188 This archive includes userspace application w1d.c which uses 189 read/write/search commands for all master/slave devices found on the bus.