0001 ===============================================
0002 Userspace communication protocol over connector
0003 ===============================================
0004
0005 Message types
0006 =============
0007
0008 There are three types of messages between w1 core and userspace:
0009
0010 1. Events. They are generated each time a new master or slave device
0011 is found either due to automatic or requested search.
0012 2. Userspace commands.
0013 3. Replies to userspace commands.
0014
0015
0016 Protocol
0017 ========
0018
0019 ::
0020
0021 [struct cn_msg] - connector header.
0022 Its length field is equal to size of the attached data
0023 [struct w1_netlink_msg] - w1 netlink header.
0024 __u8 type - message type.
0025 W1_LIST_MASTERS
0026 list current bus masters
0027 W1_SLAVE_ADD/W1_SLAVE_REMOVE
0028 slave add/remove events
0029 W1_MASTER_ADD/W1_MASTER_REMOVE
0030 master add/remove events
0031 W1_MASTER_CMD
0032 userspace command for bus master
0033 device (search/alarm search)
0034 W1_SLAVE_CMD
0035 userspace command for slave device
0036 (read/write/touch)
0037 __u8 status - error indication from kernel
0038 __u16 len - size of data attached to this header data
0039 union {
0040 __u8 id[8]; - slave unique device id
0041 struct w1_mst {
0042 __u32 id; - master's id
0043 __u32 res; - reserved
0044 } mst;
0045 } id;
0046
0047 [struct w1_netlink_cmd] - command for given master or slave device.
0048 __u8 cmd - command opcode.
0049 W1_CMD_READ - read command
0050 W1_CMD_WRITE - write command
0051 W1_CMD_SEARCH - search command
0052 W1_CMD_ALARM_SEARCH - alarm search command
0053 W1_CMD_TOUCH - touch command
0054 (write and sample data back to userspace)
0055 W1_CMD_RESET - send bus reset
0056 W1_CMD_SLAVE_ADD - add slave to kernel list
0057 W1_CMD_SLAVE_REMOVE - remove slave from kernel list
0058 W1_CMD_LIST_SLAVES - get slaves list from kernel
0059 __u8 res - reserved
0060 __u16 len - length of data for this command
0061 For read command data must be allocated like for write command
0062 __u8 data[0] - data for this command
0063
0064
0065 Each connector message can include one or more w1_netlink_msg with
0066 zero or more attached w1_netlink_cmd messages.
0067
0068 For event messages there are no w1_netlink_cmd embedded structures,
0069 only connector header and w1_netlink_msg strucutre with "len" field
0070 being zero and filled type (one of event types) and id:
0071 either 8 bytes of slave unique id in host order,
0072 or master's id, which is assigned to bus master device
0073 when it is added to w1 core.
0074
0075 Currently replies to userspace commands are only generated for read
0076 command request. One reply is generated exactly for one w1_netlink_cmd
0077 read request. Replies are not combined when sent - i.e. typical reply
0078 messages looks like the following::
0079
0080 [cn_msg][w1_netlink_msg][w1_netlink_cmd]
0081 cn_msg.len = sizeof(struct w1_netlink_msg) +
0082 sizeof(struct w1_netlink_cmd) +
0083 cmd->len;
0084 w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
0085 w1_netlink_cmd.len = cmd->len;
0086
0087 Replies to W1_LIST_MASTERS should send a message back to the userspace
0088 which will contain list of all registered master ids in the following
0089 format::
0090
0091 cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
0092 w1_netlink_msg) plus number of masters multiplied by 4)
0093 w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to
0094 number of masters multiplied by 4 (u32 size))
0095 id0 ... idN
0096
0097 Each message is at most 4k in size, so if number of master devices
0098 exceeds this, it will be split into several messages.
0099
0100 W1 search and alarm search commands.
0101
0102 request::
0103
0104 [cn_msg]
0105 [w1_netlink_msg type = W1_MASTER_CMD
0106 id is equal to the bus master id to use for searching]
0107 [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
0108
0109 reply::
0110
0111 [cn_msg, ack = 1 and increasing, 0 means the last message,
0112 seq is equal to the request seq]
0113 [w1_netlink_msg type = W1_MASTER_CMD]
0114 [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
0115 len is equal to number of IDs multiplied by 8]
0116 [64bit-id0 ... 64bit-idN]
0117
0118 Length in each header corresponds to the size of the data behind it, so
0119 w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
0120 Can be zero.
0121
0122 ::
0123
0124 w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
0125 cn_msg->len = sizeof(struct w1_netlink_msg) +
0126 sizeof(struct w1_netlink_cmd) +
0127 N*8;
0128
0129 W1 reset command::
0130
0131 [cn_msg]
0132 [w1_netlink_msg type = W1_MASTER_CMD
0133 id is equal to the bus master id to use for searching]
0134 [w1_netlink_cmd cmd = W1_CMD_RESET]
0135
0136
0137 Command status replies
0138 ======================
0139
0140 Each command (either root, master or slave with or without w1_netlink_cmd
0141 structure) will be 'acked' by the w1 core. Format of the reply is the same
0142 as request message except that length parameters do not account for data
0143 requested by the user, i.e. read/write/touch IO requests will not contain
0144 data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size
0145 of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum
0146 of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd).
0147 If reply is generated for master or root command (which do not have
0148 w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg
0149 structures.
0150
0151 w1_netlink_msg.status field will carry positive error value
0152 (EINVAL for example) or zero in case of success.
0153
0154 All other fields in every structure will mirror the same parameters in the
0155 request message (except lengths as described above).
0156
0157 Status reply is generated for every w1_netlink_cmd embedded in the
0158 w1_netlink_msg, if there are no w1_netlink_cmd structures,
0159 reply will be generated for the w1_netlink_msg.
0160
0161 All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
0162 even if there were errors, only length mismatch interrupts message processing.
0163
0164
0165 Operation steps in w1 core when new command is received
0166 =======================================================
0167
0168 When new message (w1_netlink_msg) is received w1 core detects if it is
0169 master or slave request, according to w1_netlink_msg.type field.
0170 Then master or slave device is searched for.
0171 When found, master device (requested or those one on where slave device
0172 is found) is locked. If slave command is requested, then reset/select
0173 procedure is started to select given device.
0174
0175 Then all requested in w1_netlink_msg operations are performed one by one.
0176 If command requires reply (like read command) it is sent on command completion.
0177
0178 When all commands (w1_netlink_cmd) are processed master device is unlocked
0179 and next w1_netlink_msg header processing started.
0180
0181
0182 Connector [1] specific documentation
0183 ====================================
0184
0185 Each connector message includes two u32 fields as "address".
0186 w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
0187 Each message also includes sequence and acknowledge numbers.
0188 Sequence number for event messages is appropriate bus master sequence number
0189 increased with each event message sent "through" this master.
0190 Sequence number for userspace requests is set by userspace application.
0191 Sequence number for reply is the same as was in request, and
0192 acknowledge number is set to seq+1.
0193
0194
0195 Additional documentation, source code examples
0196 ==============================================
0197
0198 1. Documentation/driver-api/connector.rst
0199 2. http://www.ioremap.net/archive/w1
0200
0201 This archive includes userspace application w1d.c which uses
0202 read/write/search commands for all master/slave devices found on the bus.
