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 | ||
b191ba0d | 72 | int cn_netlink_send(struct cn_msg *msg, u32 __groups, int gfp_mask); |
7672d0b5 EP |
73 | |
74 | Sends message to the specified groups. It can be safely called from | |
b191ba0d EP |
75 | softirq context, but may silently fail under strong memory pressure. |
76 | If there are no listeners for given group -ESRCH can be returned. | |
7672d0b5 EP |
77 | |
78 | struct cn_msg * - message header(with attached data). | |
79 | u32 __group - destination group. | |
80 | If __group is zero, then appropriate group will | |
81 | be searched through all registered connector users, | |
82 | and message will be delivered to the group which was | |
83 | created for user with the same ID as in msg. | |
84 | If __group is not zero, then message will be delivered | |
85 | to the specified group. | |
86 | int gfp_mask - GFP mask. | |
87 | ||
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 | ||
91 | /*****************************************/ | |
92 | Protocol description. | |
93 | /*****************************************/ | |
94 | ||
95 | Current offers transport layer with fixed header. Recommended | |
96 | protocol which uses such header is following: | |
97 | ||
98 | 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 | nlmsghdr->nlmsg_seq too. | |
102 | ||
103 | Sequence number is incremented with each message to be sent. | |
104 | ||
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. | |
108 | ||
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. | |
114 | ||
115 | Obviously, protocol header contains above id. | |
116 | ||
117 | connector allows event notification in the following form: kernel | |
118 | 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}). | |
122 | ||
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. | |
126 | ||
127 | /*****************************************/ | |
128 | Reliability. | |
129 | /*****************************************/ | |
130 | ||
131 | Netlink itself is not reliable protocol, that means that messages can | |
132 | 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. | |
eb0d6041 EP |
135 | |
136 | /*****************************************/ | |
137 | Userspace usage. | |
138 | /*****************************************/ | |
139 | 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: | |
144 | ||
145 | s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); | |
146 | ||
147 | l_local.nl_family = AF_NETLINK; | |
148 | l_local.nl_groups = 12345; | |
149 | l_local.nl_pid = 0; | |
150 | ||
151 | if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { | |
152 | perror("bind"); | |
153 | close(s); | |
154 | return -1; | |
155 | } | |
156 | ||
157 | { | |
158 | int on = l_local.nl_groups; | |
159 | setsockopt(s, 270, 1, &on, sizeof(on)); | |
160 | } | |
161 | ||
162 | 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. | |
165 | ||
166 | 2.6.14 netlink code only allows to select a group which is less or equal to | |
167 | the maximum group number, which is used at netlink_kernel_create() time. | |
168 | In case of connector it is CN_NETLINK_USERS + 0xf, so if you want to use | |
169 | group number 12345, you must increment CN_NETLINK_USERS to that number. | |
170 | Additional 0xf numbers are allocated to be used by non-in-kernel users. | |
171 | ||
172 | Due to this limitation, group 0xffffffff does not work now, so one can | |
173 | not use add/remove connector's group notifications, but as far as I know, | |
174 | only cn_test.c test module used it. | |
175 | ||
176 | Some work in netlink area is still being done, so things can be changed in | |
177 | 2.6.15 timeframe, if it will happen, documentation will be updated for that | |
178 | kernel. |