^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Userspace communication protocol over connector
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Message types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) There are three types of messages between w1 core and userspace:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) 1. Events. They are generated each time a new master or slave device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) is found either due to automatic or requested search.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) 2. Userspace commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) 3. Replies to userspace commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) Protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) [struct cn_msg] - connector header.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) Its length field is equal to size of the attached data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) [struct w1_netlink_msg] - w1 netlink header.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) __u8 type - message type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) W1_LIST_MASTERS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) list current bus masters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) W1_SLAVE_ADD/W1_SLAVE_REMOVE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) slave add/remove events
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) W1_MASTER_ADD/W1_MASTER_REMOVE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) master add/remove events
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) W1_MASTER_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) userspace command for bus master
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) device (search/alarm search)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) W1_SLAVE_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) userspace command for slave device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) (read/write/touch)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) __u8 status - error indication from kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) __u16 len - size of data attached to this header data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) union {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) __u8 id[8]; - slave unique device id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) struct w1_mst {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) __u32 id; - master's id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) __u32 res; - reserved
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) } mst;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) } id;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) [struct w1_netlink_cmd] - command for given master or slave device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) __u8 cmd - command opcode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) W1_CMD_READ - read command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) W1_CMD_WRITE - write command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) W1_CMD_SEARCH - search command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) W1_CMD_ALARM_SEARCH - alarm search command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) W1_CMD_TOUCH - touch command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) (write and sample data back to userspace)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) W1_CMD_RESET - send bus reset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) W1_CMD_SLAVE_ADD - add slave to kernel list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) W1_CMD_SLAVE_REMOVE - remove slave from kernel list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) W1_CMD_LIST_SLAVES - get slaves list from kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) __u8 res - reserved
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) __u16 len - length of data for this command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) For read command data must be allocated like for write command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) __u8 data[0] - data for this command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) Each connector message can include one or more w1_netlink_msg with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) zero or more attached w1_netlink_cmd messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) For event messages there are no w1_netlink_cmd embedded structures,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) only connector header and w1_netlink_msg strucutre with "len" field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) being zero and filled type (one of event types) and id:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) either 8 bytes of slave unique id in host order,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) or master's id, which is assigned to bus master device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) when it is added to w1 core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) Currently replies to userspace commands are only generated for read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) command request. One reply is generated exactly for one w1_netlink_cmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) read request. Replies are not combined when sent - i.e. typical reply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) messages looks like the following::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) [cn_msg][w1_netlink_msg][w1_netlink_cmd]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) cn_msg.len = sizeof(struct w1_netlink_msg) +
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) sizeof(struct w1_netlink_cmd) +
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) cmd->len;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) w1_netlink_cmd.len = cmd->len;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) Replies to W1_LIST_MASTERS should send a message back to the userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) which will contain list of all registered master ids in the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) format::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) w1_netlink_msg) plus number of masters multiplied by 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) number of masters multiplied by 4 (u32 size))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) id0 ... idN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) Each message is at most 4k in size, so if number of master devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) exceeds this, it will be split into several messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) W1 search and alarm search commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) request::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) [cn_msg]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) [w1_netlink_msg type = W1_MASTER_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) id is equal to the bus master id to use for searching]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) reply::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) [cn_msg, ack = 1 and increasing, 0 means the last message,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) seq is equal to the request seq]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) [w1_netlink_msg type = W1_MASTER_CMD]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) len is equal to number of IDs multiplied by 8]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) [64bit-id0 ... 64bit-idN]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) Length in each header corresponds to the size of the data behind it, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Can be zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) cn_msg->len = sizeof(struct w1_netlink_msg) +
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) sizeof(struct w1_netlink_cmd) +
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) N*8;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) W1 reset command::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) [cn_msg]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) [w1_netlink_msg type = W1_MASTER_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) id is equal to the bus master id to use for searching]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) [w1_netlink_cmd cmd = W1_CMD_RESET]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) Command status replies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) Each command (either root, master or slave with or without w1_netlink_cmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) structure) will be 'acked' by the w1 core. Format of the reply is the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) as request message except that length parameters do not account for data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) requested by the user, i.e. read/write/touch IO requests will not contain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) If reply is generated for master or root command (which do not have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) structures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) w1_netlink_msg.status field will carry positive error value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) (EINVAL for example) or zero in case of success.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) All other fields in every structure will mirror the same parameters in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) request message (except lengths as described above).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) Status reply is generated for every w1_netlink_cmd embedded in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) w1_netlink_msg, if there are no w1_netlink_cmd structures,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) reply will be generated for the w1_netlink_msg.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) even if there were errors, only length mismatch interrupts message processing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) Operation steps in w1 core when new command is received
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) =======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) When new message (w1_netlink_msg) is received w1 core detects if it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) master or slave request, according to w1_netlink_msg.type field.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) Then master or slave device is searched for.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) When found, master device (requested or those one on where slave device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) is found) is locked. If slave command is requested, then reset/select
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) procedure is started to select given device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) Then all requested in w1_netlink_msg operations are performed one by one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) If command requires reply (like read command) it is sent on command completion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) When all commands (w1_netlink_cmd) are processed master device is unlocked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) and next w1_netlink_msg header processing started.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) Connector [1] specific documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) ====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) Each connector message includes two u32 fields as "address".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) Each message also includes sequence and acknowledge numbers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) Sequence number for event messages is appropriate bus master sequence number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) increased with each event message sent "through" this master.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) Sequence number for userspace requests is set by userspace application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) Sequence number for reply is the same as was in request, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) acknowledge number is set to seq+1.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) Additional documentation, source code examples
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) ==============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) 1. Documentation/driver-api/connector.rst
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) 2. http://www.ioremap.net/archive/w1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) This archive includes userspace application w1d.c which uses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) read/write/search commands for all master/slave devices found on the bus.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags