blob: 3640c7c87d457683e249fe57df0c654b0c7d439f [file] [log] [blame]
Evgeniy Polyakov12003372006-03-23 19:11:58 +03001Userspace 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 found
9 either due to automatic or requested search.
102. Userspace commands. Includes read/write and search/alarm search comamnds.
113. Replies to userspace commands.
12
13
14Protocol.
15========
16
17[struct cn_msg] - connector header. It's length field is equal to size of the attached data.
18[struct w1_netlink_msg] - w1 netlink header.
19 __u8 type - message type.
20 W1_SLAVE_ADD/W1_SLAVE_REMOVE - slave add/remove events.
21 W1_MASTER_ADD/W1_MASTER_REMOVE - master add/remove events.
22 W1_MASTER_CMD - userspace command for bus master device (search/alarm search).
23 W1_SLAVE_CMD - userspace command for slave device (read/write/ search/alarm search
24 for bus master device where given slave device found).
25 __u8 res - reserved
26 __u16 len - size of attached to this header data.
27 union {
28 __u8 id; - slave unique device id
29 struct w1_mst {
30 __u32 id; - master's id.
31 __u32 res; - reserved
32 } mst;
33 } id;
34
35[strucrt w1_netlink_cmd] - command for gived master or slave device.
36 __u8 cmd - command opcode.
37 W1_CMD_READ - read command.
38 W1_CMD_WRITE - write command.
39 W1_CMD_SEARCH - search command.
40 W1_CMD_ALARM_SEARCH - alarm search command.
41 __u8 res - reserved
42 __u16 len - length of data for this command.
43 For read command data must be allocated like for write command.
44 __u8 data[0] - data for this command.
45
46
47Each connector message can include one or more w1_netlink_msg with zero of more attached w1_netlink_cmd messages.
48
49For event messages there are no w1_netlink_cmd embedded structures, only connector header
50and w1_netlink_msg strucutre with "len" field being zero and filled type (one of event types)
51and id - either 8 bytes of slave unique id in host order, or master's id, which is assigned
52to bus master device when it is added to w1 core.
53
54Currently replies to userspace commands are only generated for read command request.
55One reply is generated exactly for one w1_netlink_cmd read request.
56Replies are not combined when sent - i.e. typical reply messages looks like the following:
57[cn_msg][w1_netlink_msg][w1_netlink_cmd]
58cn_msg.len = sizeof(struct w1_netlink_msg) + sizeof(struct w1_netlink_cmd) + cmd->len;
59w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
60w1_netlink_cmd.len = cmd->len;
61
62
63Operation steps in w1 core when new command is received.
64=======================================================
65
66When new message (w1_netlink_msg) is received w1 core detects if it is master of slave request,
67according to w1_netlink_msg.type field.
68Then master or slave device is searched for.
69When found, master device (requested or those one on where slave device is found) is locked.
70If slave command is requested, then reset/select procedure is started to select given device.
71
72Then all requested in w1_netlink_msg operations are performed one by one.
73If command requires reply (like read command) it is sent on command completion.
74
75When all commands (w1_netlink_cmd) are processed muster device is unlocked
76and next w1_netlink_msg header processing started.
77
78
79Connector [1] specific documentation.
80====================================
81
82Each connector message includes two u32 fields as "address".
83w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
84Each message also includes sequence and acknowledge numbers.
85Sequence number for event messages is appropriate bus master sequence number increased with
86each event message sent "through" this master.
87Sequence number for userspace requests is set by userspace application.
88Sequence number for reply is the same as was in request, and
89acknowledge number is set to seq+1.
90
91
92Additional documantion, source code examples.
93============================================
94
951. Documentation/connector
962. http://tservice.net.ru/~s0mbre/archive/w1
97This archive includes userspace application w1d.c which
98uses read/write/search commands for all master/slave devices found on the bus.