[net-next-2.6.git] / Documentation / w1 / w1.netlink

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 new master or slave device
	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 res	- reserved
	__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_TOUCH	- touch command
				(write and sample data back to userspace)
			W1_CMD_SEARCH	- search command
			W1_CMD_ALARM_SEARCH - alarm search command
	__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 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;

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
structires.

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 muster 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/connector
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.
Commit	Line	Data
12003375 EP	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:
e4e056aa EP	8	1. Events. They are generated each time new master or slave device
	9	found either due to automatic or requested search.
	10	2. Userspace commands.
12003375 EP	11	3. Replies to userspace commands.
	12
	13
	14	Protocol.
	15	========
	16
e4e056aa EP	17	[struct cn_msg] - connector header.
e4e056aa EP	18	Its length field is equal to size of the attached data
12003375 EP	19	[struct w1_netlink_msg] - w1 netlink header.
12003375 EP	20	__u8 type - message type.
e4e056aa EP	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)
12003375	33	__u8 res - reserved
e4e056aa	34	__u16 len - size of data attached to this header data
12003375	35	union {
e4e056aa	36	__u8 id[8]; - slave unique device id
12003375	37	struct w1_mst {
e4e056aa	38	__u32 id; - master's id
12003375 EP	39	__u32 res; - reserved
	40	} mst;
	41	} id;
	42
e4e056aa	43	[struct w1_netlink_cmd] - command for given master or slave device.
12003375	44	__u8 cmd - command opcode.
e4e056aa EP	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
12003375	51	__u8 res - reserved
e4e056aa EP	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
12003375 EP	55
12003375 EP	56
e4e056aa EP	57	Each connector message can include one or more w1_netlink_msg with
e4e056aa EP	58	zero or more attached w1_netlink_cmd messages.
12003375	59
e4e056aa EP	60	For event messages there are no w1_netlink_cmd embedded structures,
	61	only connector header and w1_netlink_msg strucutre with "len" field
	62	being zero and filled type (one of event types) and id:
	63	either 8 bytes of slave unique id in host order,
	64	or master's id, which is assigned to bus master device
	65	when it is added to w1 core.
	66
	67	Currently replies to userspace commands are only generated for read
	68	command request. One reply is generated exactly for one w1_netlink_cmd
	69	read request. Replies are not combined when sent - i.e. typical reply
	70	messages looks like the following:
12003375	71
12003375	72	[cn_msg][w1_netlink_msg][w1_netlink_cmd]
e4e056aa EP	73	cn_msg.len = sizeof(struct w1_netlink_msg) +
	74	sizeof(struct w1_netlink_cmd) +
	75	cmd->len;
12003375 EP	76	w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
	77	w1_netlink_cmd.len = cmd->len;
	78
e4e056aa EP	79	Replies to W1_LIST_MASTERS should send a message back to the userspace
	80	which will contain list of all registered master ids in the following
	81	format:
	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 multipled 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
	93	W1 search and alarm search commands.
	94	request:
	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
	100	reply:
	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]
	107	Length in each header corresponds to the size of the data behind it, so
	108	w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
	109	Can be zero.
	110	w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
	111	cn_msg->len = sizeof(struct w1_netlink_msg) +
	112	sizeof(struct w1_netlink_cmd) +
	113	N*8;
12003375	114
f89735c4 EP	115	W1 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
4037014e EP	121
	122	Command status replies.
	123	======================
	124
	125	Each command (either root, master or slave with or without w1_netlink_cmd
	126	structure) will be 'acked' by the w1 core. Format of the reply is the same
	127	as request message except that length parameters do not account for data
	128	requested by the user, i.e. read/write/touch IO requests will not contain
	129	data, so w1_netlink_cmd.len will be 0, w1_netlink_msg.len will be size
	130	of the w1_netlink_cmd structure and cn_msg.len will be equal to the sum
	131	of the sizeof(struct w1_netlink_msg) and sizeof(struct w1_netlink_cmd).
	132	If reply is generated for master or root command (which do not have
	133	w1_netlink_cmd attached), reply will contain only cn_msg and w1_netlink_msg
	134	structires.
	135
	136	w1_netlink_msg.status field will carry positive error value
	137	(EINVAL for example) or zero in case of success.
	138
	139	All other fields in every structure will mirror the same parameters in the
	140	request message (except lengths as described above).
	141
	142	Status reply is generated for every w1_netlink_cmd embedded in the
	143	w1_netlink_msg, if there are no w1_netlink_cmd structures,
	144	reply will be generated for the w1_netlink_msg.
	145
	146	All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
	147	even if there were errors, only length mismatch interrupts message processing.
	148
	149
12003375 EP	150	Operation steps in w1 core when new command is received.
	151	=======================================================
	152
e4e056aa EP	153	When new message (w1_netlink_msg) is received w1 core detects if it is
e4e056aa EP	154	master or slave request, according to w1_netlink_msg.type field.
12003375	155	Then master or slave device is searched for.
e4e056aa EP	156	When found, master device (requested or those one on where slave device
	157	is found) is locked. If slave command is requested, then reset/select
	158	procedure is started to select given device.
12003375 EP	159
	160	Then all requested in w1_netlink_msg operations are performed one by one.
	161	If command requires reply (like read command) it is sent on command completion.
	162
	163	When all commands (w1_netlink_cmd) are processed muster device is unlocked
	164	and next w1_netlink_msg header processing started.
	165
	166
	167	Connector [1] specific documentation.
	168	====================================
	169
	170	Each connector message includes two u32 fields as "address".
	171	w1 uses CN_W1_IDX and CN_W1_VAL defined in include/linux/connector.h header.
	172	Each message also includes sequence and acknowledge numbers.
e4e056aa EP	173	Sequence number for event messages is appropriate bus master sequence number
e4e056aa EP	174	increased with each event message sent "through" this master.
12003375 EP	175	Sequence number for userspace requests is set by userspace application.
	176	Sequence number for reply is the same as was in request, and
	177	acknowledge number is set to seq+1.
	178
	179
	180	Additional documantion, source code examples.
	181	============================================
	182
	183	1. Documentation/connector
e4e056aa EP	184	2. http://www.ioremap.net/archive/w1
	185	This archive includes userspace application w1d.c which uses
	186	read/write/search commands for all master/slave devices found on the bus.