About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / w1 / w1.netlink


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog