diff options
Diffstat (limited to 'Documentation/w1/w1.netlink')
-rw-r--r-- | Documentation/w1/w1.netlink | 189 |
1 files changed, 0 insertions, 189 deletions
diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1.netlink deleted file mode 100644 index 94ad4c420828..000000000000 --- a/Documentation/w1/w1.netlink +++ /dev/null @@ -1,189 +0,0 @@ -Userspace communication protocol over connector [1]. - - -Message types. -============= - -There are three types of messages between w1 core and userspace: -1. Events. They are generated each time a new master or slave device - is found either due to automatic or requested search. -2. Userspace commands. -3. Replies to userspace commands. - - -Protocol. -======== - -[struct cn_msg] - connector header. - Its length field is equal to size of the attached data -[struct w1_netlink_msg] - w1 netlink header. - __u8 type - message type. - W1_LIST_MASTERS - list current bus masters - W1_SLAVE_ADD/W1_SLAVE_REMOVE - slave add/remove events - W1_MASTER_ADD/W1_MASTER_REMOVE - master add/remove events - W1_MASTER_CMD - userspace command for bus master - device (search/alarm search) - W1_SLAVE_CMD - userspace command for slave device - (read/write/touch) - __u8 status - error indication from kernel - __u16 len - size of data attached to this header data - union { - __u8 id[8]; - slave unique device id - struct w1_mst { - __u32 id; - master's id - __u32 res; - reserved - } mst; - } id; - -[struct w1_netlink_cmd] - command for given master or slave device. - __u8 cmd - command opcode. - W1_CMD_READ - read command - W1_CMD_WRITE - write command - W1_CMD_SEARCH - search command - W1_CMD_ALARM_SEARCH - alarm search command - W1_CMD_TOUCH - touch command - (write and sample data back to userspace) - W1_CMD_RESET - send bus reset - W1_CMD_SLAVE_ADD - add slave to kernel list - W1_CMD_SLAVE_REMOVE - remove slave from kernel list - W1_CMD_LIST_SLAVES - get slaves list from kernel - __u8 res - reserved - __u16 len - length of data for this command - For read command data must be allocated like for write command - __u8 data[0] - data for this command - - -Each connector message can include one or more w1_netlink_msg with -zero or more attached w1_netlink_cmd messages. - -For event messages there are no w1_netlink_cmd embedded structures, -only connector header and w1_netlink_msg strucutre with "len" field -being zero and filled type (one of event types) and id: -either 8 bytes of slave unique id in host order, -or master's id, which is assigned to bus master device -when it is added to w1 core. - -Currently replies to userspace commands are only generated for read -command request. One reply is generated exactly for one w1_netlink_cmd -read request. Replies are not combined when sent - i.e. typical reply -messages looks like the following: - -[cn_msg][w1_netlink_msg][w1_netlink_cmd] -cn_msg.len = sizeof(struct w1_netlink_msg) + - sizeof(struct w1_netlink_cmd) + - cmd->len; -w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; -w1_netlink_cmd.len = cmd->len; - -Replies to W1_LIST_MASTERS should send a message back to the userspace -which will contain list of all registered master ids in the following -format: - - cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct - w1_netlink_msg) plus number of masters multiplied by 4) - w1_netlink_msg (type: W1_LIST_MASTERS, len is equal to - number of masters multiplied by 4 (u32 size)) - id0 ... idN - - Each message is at most 4k in size, so if number of master devices - exceeds this, it will be split into several messages. - -W1 search and alarm search commands. -request: -[cn_msg] - [w1_netlink_msg type = W1_MASTER_CMD - id is equal to the bus master id to use for searching] - [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH] - -reply: - [cn_msg, ack = 1 and increasing, 0 means the last message, - seq is equal to the request seq] - [w1_netlink_msg type = W1_MASTER_CMD] - [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH - len is equal to number of IDs multiplied by 8] - [64bit-id0 ... 64bit-idN] -Length in each header corresponds to the size of the data behind it, so -w1_netlink_cmd->len = N * 8; where N is number of IDs in this message. - Can be zero. -w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8; -cn_msg->len = sizeof(struct w1_netlink_msg) + - sizeof(struct w1_netlink_cmd) + - N*8; - -W1 reset command. -[cn_msg] - [w1_netlink_msg type = W1_MASTER_CMD - id is equal to the bus master id to use for searching] - [w1_netlink_cmd cmd = W1_CMD_RESET] - - -Command status replies. -====================== - -Each command (either root, master or slave with or without w1_netlink_cmd -structure) will be 'acked' by the w1 core. Format of the reply is the same -as request message except that length parameters do not account for data -requested by the user, i.e. read/write/touch IO requests will not contain -data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size -of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum -of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd). -If reply is generated for master or root command (which do not have -w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg -structures. - -w1_netlink_msg.status field will carry positive error value -(EINVAL for example) or zero in case of success. - -All other fields in every structure will mirror the same parameters in the -request message (except lengths as described above). - -Status reply is generated for every w1_netlink_cmd embedded in the -w1_netlink_msg, if there are no w1_netlink_cmd structures, -reply will be generated for the w1_netlink_msg. - -All w1_netlink_cmd command structures are handled in every w1_netlink_msg, -even if there were errors, only length mismatch interrupts message processing. - - -Operation steps in w1 core when new command is received. -======================================================= - -When new message (w1_netlink_msg) is received w1 core detects if it is -master or slave request, according to w1_netlink_msg.type field. -Then master or slave device is searched for. -When found, master device (requested or those one on where slave device -is found) is locked. If slave command is requested, then reset/select -procedure is started to select given device. - -Then all requested in w1_netlink_msg operations are performed one by one. -If command requires reply (like read command) it is sent on command completion. - -When all commands (w1_netlink_cmd) are processed master device is unlocked -and next w1_netlink_msg header processing started. - - -Connector [1] specific documentation. -==================================== - -Each connector message includes two u32 fields as "address". -w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header. -Each message also includes sequence and acknowledge numbers. -Sequence number for event messages is appropriate bus master sequence number -increased with each event message sent "through" this master. -Sequence number for userspace requests is set by userspace application. -Sequence number for reply is the same as was in request, and -acknowledge number is set to seq+1. - - -Additional documantion, source code examples. -============================================ - -1. Documentation/driver-api/connector.rst -2. http://www.ioremap.net/archive/w1 -This archive includes userspace application w1d.c which uses -read/write/search commands for all master/slave devices found on the bus. |