]>
Commit | Line | Data |
---|---|---|
7672d0b5 EP |
1 | /*****************************************/ |
2 | Kernel Connector. | |
3 | /*****************************************/ | |
4 | ||
5 | Kernel connector - new netlink based userspace <-> kernel space easy | |
6 | to use communication module. | |
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. | |
12 | ||
13 | From the userspace point of view it's quite straightforward: | |
14 | ||
15 | socket(); | |
16 | bind(); | |
17 | send(); | |
18 | recv(); | |
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 | |
24 | easier way: | |
25 | ||
26 | int cn_add_callback(struct cb_id *id, char *name, void (*callback) (void *)); | |
27 | void cn_netlink_send(struct cn_msg *msg, u32 __group, int gfp_mask); | |
28 | ||
29 | struct cb_id | |
30 | { | |
31 | __u32 idx; | |
32 | __u32 val; | |
33 | }; | |
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 | |
39 | be dereferenced to struct cn_msg *. | |
40 | ||
41 | struct cn_msg | |
42 | { | |
43 | struct cb_id id; | |
44 | ||
45 | __u32 seq; | |
46 | __u32 ack; | |
47 | ||
48 | __u32 len; /* Length of the following data */ | |
49 | __u8 data[0]; | |
50 | }; | |
51 | ||
52 | /*****************************************/ | |
53 | Connector interfaces. | |
54 | /*****************************************/ | |
55 | ||
56 | int cn_add_callback(struct cb_id *id, char *name, void (*callback) (void *)); | |
57 | ||
58 | Registers new callback with connector core. | |
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. | |
64 | Argument must be dereferenced to struct cn_msg *. | |
65 | ||
66 | void cn_del_callback(struct cb_id *id); | |
67 | ||
68 | Unregisters new callback with connector core. | |
69 | ||
70 | struct cb_id *id - unique connector's user identifier. | |
71 | ||
72 | void cn_netlink_send(struct cn_msg *msg, u32 __groups, int gfp_mask); | |
73 | ||
74 | Sends message to the specified groups. It can be safely called from | |
75 | any context, but may silently fail under strong memory pressure. | |
76 | ||
77 | struct cn_msg * - message header(with attached data). | |
78 | u32 __group - destination group. | |
79 | If __group is zero, then appropriate group will | |
80 | be searched through all registered connector users, | |
81 | and message will be delivered to the group which was | |
82 | created for user with the same ID as in msg. | |
83 | If __group is not zero, then message will be delivered | |
84 | to the specified group. | |
85 | int gfp_mask - GFP mask. | |
86 | ||
87 | Note: When registering new callback user, connector core assigns | |
88 | netlink group to the user which is equal to it's id.idx. | |
89 | ||
90 | /*****************************************/ | |
91 | Protocol description. | |
92 | /*****************************************/ | |
93 | ||
94 | Current offers transport layer with fixed header. Recommended | |
95 | protocol which uses such header is following: | |
96 | ||
97 | msg->seq and msg->ack are used to determine message genealogy. When | |
98 | someone sends message it puts there locally unique sequence and random | |
99 | acknowledge numbers. Sequence number may be copied into | |
100 | nlmsghdr->nlmsg_seq too. | |
101 | ||
102 | Sequence number is incremented with each message to be sent. | |
103 | ||
104 | If we expect reply to our message, then sequence number in received | |
105 | message MUST be the same as in original message, and acknowledge | |
106 | number MUST be the same + 1. | |
107 | ||
108 | If we receive message and it's sequence number is not equal to one we | |
109 | are expecting, then it is new message. If we receive message and it's | |
110 | sequence number is the same as one we are expecting, but it's | |
111 | acknowledge is not equal acknowledge number in original message + 1, | |
112 | then it is new message. | |
113 | ||
114 | Obviously, protocol header contains above id. | |
115 | ||
116 | connector allows event notification in the following form: kernel | |
117 | driver or userspace process can ask connector to notify it when | |
118 | selected id's will be turned on or off(registered or unregistered it's | |
119 | callback). It is done by sending special command to connector | |
120 | driver(it also registers itself with id={-1, -1}). | |
121 | ||
122 | As example of usage Documentation/connector now contains cn_test.c - | |
123 | testing module which uses connector to request notification and to | |
124 | send messages. | |
125 | ||
126 | /*****************************************/ | |
127 | Reliability. | |
128 | /*****************************************/ | |
129 | ||
130 | Netlink itself is not reliable protocol, that means that messages can | |
131 | be lost due to memory pressure or process' receiving queue overflowed, | |
132 | so caller is warned must be prepared. That is why struct cn_msg [main | |
133 | connector's message header] contains u32 seq and u32 ack fields. | |
eb0d6041 EP |
134 | |
135 | /*****************************************/ | |
136 | Userspace usage. | |
137 | /*****************************************/ | |
138 | 2.6.14 has a new netlink socket implementation, which by default does not | |
139 | allow to send data to netlink groups other than 1. | |
140 | So, if to use netlink socket (for example using connector) | |
141 | with different group number userspace application must subscribe to | |
142 | that group. It can be achieved by following pseudocode: | |
143 | ||
144 | s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); | |
145 | ||
146 | l_local.nl_family = AF_NETLINK; | |
147 | l_local.nl_groups = 12345; | |
148 | l_local.nl_pid = 0; | |
149 | ||
150 | if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { | |
151 | perror("bind"); | |
152 | close(s); | |
153 | return -1; | |
154 | } | |
155 | ||
156 | { | |
157 | int on = l_local.nl_groups; | |
158 | setsockopt(s, 270, 1, &on, sizeof(on)); | |
159 | } | |
160 | ||
161 | Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket | |
162 | option. To drop multicast subscription one should call above socket option | |
163 | with NETLINK_DROP_MEMBERSHIP parameter which is defined as 0. | |
164 | ||
165 | 2.6.14 netlink code only allows to select a group which is less or equal to | |
166 | the maximum group number, which is used at netlink_kernel_create() time. | |
167 | In case of connector it is CN_NETLINK_USERS + 0xf, so if you want to use | |
168 | group number 12345, you must increment CN_NETLINK_USERS to that number. | |
169 | Additional 0xf numbers are allocated to be used by non-in-kernel users. | |
170 | ||
171 | Due to this limitation, group 0xffffffff does not work now, so one can | |
172 | not use add/remove connector's group notifications, but as far as I know, | |
173 | only cn_test.c test module used it. | |
174 | ||
175 | Some work in netlink area is still being done, so things can be changed in | |
176 | 2.6.15 timeframe, if it will happen, documentation will be updated for that | |
177 | kernel. |