aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMike Frysinger <vapier@gentoo.org>2009-07-17 13:13:58 -0400
committerDavid S. Miller <davem@davemloft.net>2009-07-17 13:13:58 -0400
commit41144ca3dda6d55b10c46d5b7d86502ccffa1c97 (patch)
treed0a766a268553cdbe7f8e7cfb61fd36c7624819a
parent0741241c6b80bfd58417e95de984d60c9e9ef2a0 (diff)
connector: clean up grammar/style in documentation
The grammar in most of this file is slightly off, and some sections are hard to read due to lack of visual clues breaking up related material. Signed-off-by: Mike Frysinger <vapier@gentoo.org> Signed-off-by: David S. Miller <davem@davemloft.net>
-rw-r--r--Documentation/connector/connector.txt119
1 files changed, 61 insertions, 58 deletions
diff --git a/Documentation/connector/connector.txt b/Documentation/connector/connector.txt
index ad6e0ba7b38c..81e6bf6ead57 100644
--- a/Documentation/connector/connector.txt
+++ b/Documentation/connector/connector.txt
@@ -5,10 +5,10 @@ Kernel Connector.
5Kernel connector - new netlink based userspace <-> kernel space easy 5Kernel connector - new netlink based userspace <-> kernel space easy
6to use communication module. 6to use communication module.
7 7
8Connector driver adds possibility to connect various agents using 8The Connector driver makes it easy to connect various agents using a
9netlink based network. One must register callback and 9netlink based network. One must register a callback and an identifier.
10identifier. When driver receives special netlink message with 10When the driver receives a special netlink message with the appropriate
11appropriate identifier, appropriate callback will be called. 11identifier, the appropriate callback will be called.
12 12
13From the userspace point of view it's quite straightforward: 13From the userspace point of view it's quite straightforward:
14 14
@@ -17,10 +17,10 @@ From the userspace point of view it's quite straightforward:
17 send(); 17 send();
18 recv(); 18 recv();
19 19
20But if kernelspace want to use full power of such connections, driver 20But if kernelspace wants to use the full power of such connections, the
21writer must create special sockets, must know about struct sk_buff 21driver writer must create special sockets, must know about struct sk_buff
22handling... Connector allows any kernelspace agents to use netlink 22handling, etc... The Connector driver allows any kernelspace agents to use
23based networking for inter-process communication in a significantly 23netlink based networking for inter-process communication in a significantly
24easier way: 24easier way:
25 25
26int cn_add_callback(struct cb_id *id, char *name, void (*callback) (void *)); 26int cn_add_callback(struct cb_id *id, char *name, void (*callback) (void *));
@@ -32,15 +32,15 @@ struct cb_id
32 __u32 val; 32 __u32 val;
33}; 33};
34 34
35idx and val are unique identifiers which must be registered in 35idx and val are unique identifiers which must be registered in the
36connector.h for in-kernel usage. void (*callback) (void *) - is a 36connector.h header for in-kernel usage. void (*callback) (void *) is a
37callback function which will be called when message with above idx.val 37callback function which will be called when a message with above idx.val
38will be received by connector core. Argument for that function must 38is received by the connector core. The argument for that function must
39be dereferenced to struct cn_msg *. 39be dereferenced to struct cn_msg *.
40 40
41struct cn_msg 41struct cn_msg
42{ 42{
43 struct cb_id id; 43 struct cb_id id;
44 44
45 __u32 seq; 45 __u32 seq;
46 __u32 ack; 46 __u32 ack;
@@ -55,92 +55,95 @@ Connector interfaces.
55 55
56int cn_add_callback(struct cb_id *id, char *name, void (*callback) (void *)); 56int cn_add_callback(struct cb_id *id, char *name, void (*callback) (void *));
57 57
58Registers new callback with connector core. 58 Registers new callback with connector core.
59 59
60struct cb_id *id - unique connector's user identifier. 60 struct cb_id *id - unique connector's user identifier.
61 It must be registered in connector.h for legal in-kernel users. 61 It must be registered in connector.h for legal in-kernel users.
62char *name - connector's callback symbolic name. 62 char *name - connector's callback symbolic name.
63void (*callback) (void *) - connector's callback. 63 void (*callback) (void *) - connector's callback.
64 Argument must be dereferenced to struct cn_msg *. 64 Argument must be dereferenced to struct cn_msg *.
65 65
66
66void cn_del_callback(struct cb_id *id); 67void cn_del_callback(struct cb_id *id);
67 68
68Unregisters new callback with connector core. 69 Unregisters new callback with connector core.
70
71 struct cb_id *id - unique connector's user identifier.
69 72
70struct cb_id *id - unique connector's user identifier.
71 73
72int cn_netlink_send(struct cn_msg *msg, u32 __groups, int gfp_mask); 74int cn_netlink_send(struct cn_msg *msg, u32 __groups, int gfp_mask);
73 75
74Sends message to the specified groups. It can be safely called from 76 Sends message to the specified groups. It can be safely called from
75softirq context, but may silently fail under strong memory pressure. 77 softirq context, but may silently fail under strong memory pressure.
76If there are no listeners for given group -ESRCH can be returned. 78 If there are no listeners for given group -ESRCH can be returned.
77 79
78struct cn_msg * - message header(with attached data). 80 struct cn_msg * - message header(with attached data).
79u32 __group - destination group. 81 u32 __group - destination group.
80 If __group is zero, then appropriate group will 82 If __group is zero, then appropriate group will
81 be searched through all registered connector users, 83 be searched through all registered connector users,
82 and message will be delivered to the group which was 84 and message will be delivered to the group which was
83 created for user with the same ID as in msg. 85 created for user with the same ID as in msg.
84 If __group is not zero, then message will be delivered 86 If __group is not zero, then message will be delivered
85 to the specified group. 87 to the specified group.
86int gfp_mask - GFP mask. 88 int gfp_mask - GFP mask.
87 89
88Note: When registering new callback user, connector core assigns 90 Note: When registering new callback user, connector core assigns
89netlink group to the user which is equal to it's id.idx. 91 netlink group to the user which is equal to it's id.idx.
90 92
91/*****************************************/ 93/*****************************************/
92Protocol description. 94Protocol description.
93/*****************************************/ 95/*****************************************/
94 96
95Current offers transport layer with fixed header. Recommended 97The current framework offers a transport layer with fixed headers. The
96protocol which uses such header is following: 98recommended protocol which uses such a header is as following:
97 99
98msg->seq and msg->ack are used to determine message genealogy. When 100msg->seq and msg->ack are used to determine message genealogy. When
99someone sends message it puts there locally unique sequence and random 101someone sends a message, they use a locally unique sequence and random
100acknowledge numbers. Sequence number may be copied into 102acknowledge number. The sequence number may be copied into
101nlmsghdr->nlmsg_seq too. 103nlmsghdr->nlmsg_seq too.
102 104
103Sequence number is incremented with each message to be sent. 105The sequence number is incremented with each message sent.
104 106
105If we expect reply to our message, then sequence number in received 107If you expect a reply to the message, then the sequence number in the
106message MUST be the same as in original message, and acknowledge 108received message MUST be the same as in the original message, and the
107number MUST be the same + 1. 109acknowledge number MUST be the same + 1.
108 110
109If we receive message and it's sequence number is not equal to one we 111If we receive a message and its sequence number is not equal to one we
110are expecting, then it is new message. If we receive message and it's 112are expecting, then it is a new message. If we receive a message and
111sequence number is the same as one we are expecting, but it's 113its sequence number is the same as one we are expecting, but its
112acknowledge is not equal acknowledge number in original message + 1, 114acknowledge is not equal to the acknowledge number in the original
113then it is new message. 115message + 1, then it is a new message.
114 116
115Obviously, protocol header contains above id. 117Obviously, the protocol header contains the above id.
116 118
117connector allows event notification in the following form: kernel 119The connector allows event notification in the following form: kernel
118driver or userspace process can ask connector to notify it when 120driver or userspace process can ask connector to notify it when
119selected id's will be turned on or off(registered or unregistered it's 121selected ids will be turned on or off (registered or unregistered its
120callback). It is done by sending special command to connector 122callback). It is done by sending a special command to the connector
121driver(it also registers itself with id={-1, -1}). 123driver (it also registers itself with id={-1, -1}).
122 124
123As example of usage Documentation/connector now contains cn_test.c - 125As example of this usage can be found in the cn_test.c module which
124testing module which uses connector to request notification and to 126uses the connector to request notification and to send messages.
125send messages.
126 127
127/*****************************************/ 128/*****************************************/
128Reliability. 129Reliability.
129/*****************************************/ 130/*****************************************/
130 131
131Netlink itself is not reliable protocol, that means that messages can 132Netlink itself is not a reliable protocol. That means that messages can
132be lost due to memory pressure or process' receiving queue overflowed, 133be lost due to memory pressure or process' receiving queue overflowed,
133so caller is warned must be prepared. That is why struct cn_msg [main 134so caller is warned that it must be prepared. That is why the struct
134connector's message header] contains u32 seq and u32 ack fields. 135cn_msg [main connector's message header] contains u32 seq and u32 ack
136fields.
135 137
136/*****************************************/ 138/*****************************************/
137Userspace usage. 139Userspace usage.
138/*****************************************/ 140/*****************************************/
141
1392.6.14 has a new netlink socket implementation, which by default does not 1422.6.14 has a new netlink socket implementation, which by default does not
140allow to send data to netlink groups other than 1. 143allow people to send data to netlink groups other than 1.
141So, if to use netlink socket (for example using connector) 144So, if you wish to use a netlink socket (for example using connector)
142with different group number userspace application must subscribe to 145with a different group number, the userspace application must subscribe to
143that group. It can be achieved by following pseudocode: 146that group first. It can be achieved by the following pseudocode:
144 147
145s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); 148s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
146 149
@@ -160,8 +163,8 @@ if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
160} 163}
161 164
162Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket 165Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket
163option. To drop multicast subscription one should call above socket option 166option. To drop a multicast subscription, one should call the above socket
164with NETLINK_DROP_MEMBERSHIP parameter which is defined as 0. 167option with the NETLINK_DROP_MEMBERSHIP parameter which is defined as 0.
165 168
1662.6.14 netlink code only allows to select a group which is less or equal to 1692.6.14 netlink code only allows to select a group which is less or equal to
167the maximum group number, which is used at netlink_kernel_create() time. 170the maximum group number, which is used at netlink_kernel_create() time.