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