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