Documentation/w1/w1-netlink.rst

   1 ===============================================
   2 Userspace communication protocol over connector
   3 ===============================================
   4
   5 Message types
   6 =============
   7
   8 There are three types of messages between w1 core and userspace:
   9
  10 1. Events. They are generated each time a new master or slave device
  11    is found either due to automatic or requested search.
  12 2. Userspace commands.
  13 3. Replies to userspace commands.
  14
  15
  16 Protocol
  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
  65 Each connector message can include one or more w1_netlink_msg with
  66 zero or more attached w1_netlink_cmd messages.
  67
  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.
  74
  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
  78 messages 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
  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
  89 format::
  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
  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.
  99
 100 W1 search and alarm search commands.
 101
 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
 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
 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.
 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) +
 126               sizeof(struct w1_netlink_cmd) +
 127               N*8;
 128
 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]
 135
 136
 137 Command status replies
 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
 149 structures.
 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
 165 Operation steps in w1 core when new command is received
 166 =======================================================
 167
 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.
 170 Then master or slave device is searched for.
 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.
 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
 178 When all commands (w1_netlink_cmd) are processed master device is unlocked
 179 and next w1_netlink_msg header processing started.
 180
 181
 182 Connector [1] specific documentation
 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.
 188 Sequence number for event messages is appropriate bus master sequence number
 189 increased with each event message sent "through" this master.
 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
 195 Additional documentation, source code examples
 196 ==============================================
 197
 198 1. Documentation/driver-api/connector.rst
 199 2. 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.