Eric Lee / linux-smarc-t335x-v3.2

Download as
Browse Code ยป

Commit 41144ca3dda6d55b10c46d5b7d86502ccffa1c97

Authored by Mike Frysinger
Committed by David S. Miller
1 parent 0741241c6b
Exists in master and in 4 other branches v3.2_AM335xPSP_04.06.00.11, v3.2_NEWT335xPSP_04.06.00.11, v3.2_SBC_SMARTMEN, v3.2_SMARCT335xPSP_04.06.00.11

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>

Showing 1 changed file with 61 additions and 58 deletions Side-by-side Diff

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