Evgeniy Polyakov | 7672d0b | 2005-09-11 19:15:07 -0700 | [diff] [blame] | 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 | |
Evgeniy Polyakov | b191ba0 | 2006-03-20 22:21:40 -0800 | [diff] [blame^] | 72 | int cn_netlink_send(struct cn_msg *msg, u32 __groups, int gfp_mask); |
Evgeniy Polyakov | 7672d0b | 2005-09-11 19:15:07 -0700 | [diff] [blame] | 73 | |
| 74 | Sends message to the specified groups. It can be safely called from |
Evgeniy Polyakov | b191ba0 | 2006-03-20 22:21:40 -0800 | [diff] [blame^] | 75 | softirq context, but may silently fail under strong memory pressure. |
| 76 | If there are no listeners for given group -ESRCH can be returned. |
Evgeniy Polyakov | 7672d0b | 2005-09-11 19:15:07 -0700 | [diff] [blame] | 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. |
Evgeniy Polyakov | eb0d604 | 2005-10-13 14:42:04 -0700 | [diff] [blame] | 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. |