提交 e4e056aa 编写于 作者: E Evgeniy Polyakov 提交者: Linus Torvalds

w1: documentation update

Signed-off-by: NEvgeniy Polyakov <zbr@ioremap.net>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>
上级 3b838407
...@@ -5,69 +5,122 @@ Message types. ...@@ -5,69 +5,122 @@ Message types.
============= =============
There are three types of messages between w1 core and userspace: There are three types of messages between w1 core and userspace:
1. Events. They are generated each time new master or slave device found 1. Events. They are generated each time new master or slave device
either due to automatic or requested search. found either due to automatic or requested search.
2. Userspace commands. Includes read/write and search/alarm search comamnds. 2. Userspace commands.
3. Replies to userspace commands. 3. Replies to userspace commands.
Protocol. Protocol.
======== ========
[struct cn_msg] - connector header. It's length field is equal to size of the attached data. [struct cn_msg] - connector header.
Its length field is equal to size of the attached data
[struct w1_netlink_msg] - w1 netlink header. [struct w1_netlink_msg] - w1 netlink header.
__u8 type - message type. __u8 type - message type.
W1_SLAVE_ADD/W1_SLAVE_REMOVE - slave add/remove events. W1_LIST_MASTERS
W1_MASTER_ADD/W1_MASTER_REMOVE - master add/remove events. list current bus masters
W1_MASTER_CMD - userspace command for bus master device (search/alarm search). W1_SLAVE_ADD/W1_SLAVE_REMOVE
W1_SLAVE_CMD - userspace command for slave device (read/write/ search/alarm search slave add/remove events
for bus master device where given slave device found). 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 res - reserved __u8 res - reserved
__u16 len - size of attached to this header data. __u16 len - size of data attached to this header data
union { union {
__u8 id; - slave unique device id __u8 id[8]; - slave unique device id
struct w1_mst { struct w1_mst {
__u32 id; - master's id. __u32 id; - master's id
__u32 res; - reserved __u32 res; - reserved
} mst; } mst;
} id; } id;
[strucrt w1_netlink_cmd] - command for gived master or slave device. [struct w1_netlink_cmd] - command for given master or slave device.
__u8 cmd - command opcode. __u8 cmd - command opcode.
W1_CMD_READ - read command. W1_CMD_READ - read command
W1_CMD_WRITE - write command. W1_CMD_WRITE - write command
W1_CMD_SEARCH - search command. W1_CMD_TOUCH - touch command
W1_CMD_ALARM_SEARCH - alarm search command. (write and sample data back to userspace)
W1_CMD_SEARCH - search command
W1_CMD_ALARM_SEARCH - alarm search command
__u8 res - reserved __u8 res - reserved
__u16 len - length of data for this command. __u16 len - length of data for this command
For read command data must be allocated like for write command. For read command data must be allocated like for write command
__u8 data[0] - data for this command. __u8 data[0] - data for this command
Each connector message can include one or more w1_netlink_msg with zero of more attached w1_netlink_cmd messages. 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 For event messages there are no w1_netlink_cmd embedded structures,
and w1_netlink_msg strucutre with "len" field being zero and filled type (one of event types) only connector header and w1_netlink_msg strucutre with "len" field
and id - either 8 bytes of slave unique id in host order, or master's id, which is assigned being zero and filled type (one of event types) and id:
to bus master device when it is added to w1 core. 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:
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][w1_netlink_msg][w1_netlink_cmd]
cn_msg.len = sizeof(struct w1_netlink_msg) + sizeof(struct w1_netlink_cmd) + cmd->len; 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_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
w1_netlink_cmd.len = 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 multipled 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,
cn.seq will be increased for each one.
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;
Operation steps in w1 core when new command is received. 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 of slave request, When new message (w1_netlink_msg) is received w1 core detects if it is
according to w1_netlink_msg.type field. master or slave request, according to w1_netlink_msg.type field.
Then master or slave device is searched for. Then master or slave device is searched for.
When found, master device (requested or those one on where slave device is found) is locked. When found, master device (requested or those one on where slave device
If slave command is requested, then reset/select procedure is started to select given 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. 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. If command requires reply (like read command) it is sent on command completion.
...@@ -82,8 +135,8 @@ Connector [1] specific documentation. ...@@ -82,8 +135,8 @@ Connector [1] specific documentation.
Each connector message includes two u32 fields as "address". 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. w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
Each message also includes sequence and acknowledge numbers. Each message also includes sequence and acknowledge numbers.
Sequence number for event messages is appropriate bus master sequence number increased with Sequence number for event messages is appropriate bus master sequence number
each event message sent "through" this master. increased with each event message sent "through" this master.
Sequence number for userspace requests is set by userspace application. Sequence number for userspace requests is set by userspace application.
Sequence number for reply is the same as was in request, and Sequence number for reply is the same as was in request, and
acknowledge number is set to seq+1. acknowledge number is set to seq+1.
...@@ -93,6 +146,6 @@ Additional documantion, source code examples. ...@@ -93,6 +146,6 @@ Additional documantion, source code examples.
============================================ ============================================
1. Documentation/connector 1. Documentation/connector
2. http://tservice.net.ru/~s0mbre/archive/w1 2. http://www.ioremap.net/archive/w1
This archive includes userspace application w1d.c which This archive includes userspace application w1d.c which uses
uses read/write/search commands for all master/slave devices found on the bus. read/write/search commands for all master/slave devices found on the bus.
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册