]>
git.ipfire.org Git - thirdparty/bird.git/blob - nest/proto-hooks.c
2 * BIRD -- Documentation for Protocol Hooks (dummy source file)
4 * (c) 2000 Martin Mares <mj@ucw.cz>
6 * Can be freely distributed and used under the terms of the GNU GPL.
12 * Each protocol can provide a rich set of hook functions referred to by pointers
13 * in either the &proto or &protocol structure. They are called by the core whenever
14 * it wants the protocol to perform some action or to notify the protocol about
15 * any change of its environment. All of the hooks can be set to %NULL which means
16 * to ignore the change or to take a default action.
20 * preconfig - protocol preconfiguration
21 * @p: a routing protocol
22 * @c: new configuration
24 * The preconfig() hook is called before parsing of a new configuration.
26 void preconfig(struct protocol
*p
, struct config
*c
)
30 * postconfig - instance post-configuration
31 * @c: instance configuration
33 * The postconfig() hook is called for each configured instance after
34 * parsing of the new configuration is finished.
36 void postconfig(struct proto_config
*c
)
40 * init - initialize an instance
41 * @c: instance configuration
43 * The init() hook is called by the core to create a protocol instance
44 * according to supplied protocol configuration.
46 * Result: a pointer to the instance created
48 struct proto
*init(struct proto_config
*c
)
52 * reconfigure - request instance reconfiguration
54 * @c: new configuration
56 * The core calls the reconfigure() hook whenever it wants to ask the
57 * protocol for switching to a new configuration. If the reconfiguration
58 * is possible, the hook returns 1. Otherwise, it returns 0 and the core
59 * will shut down the instance and start a new one with the new configuration.
61 * After the protocol confirms reconfiguration, it must no longer keep any
62 * references to the old configuration since the memory it's stored in can
63 * be re-used at any time.
65 int reconfigure(struct proto
*p
, struct proto_config
*c
)
69 * dump - dump protocol state
72 * This hook dumps the complete state of the instance to the
75 void dump(struct proto
*p
)
79 * dump_attrs - dump protocol-dependent attributes
82 * This hook dumps all attributes in the &rte which belong to this
83 * protocol to the debug output.
85 void dump_attrs(rte
*e
)
89 * start - request instance startup
90 * @p: protocol instance
92 * The start() hook is called by the core when it wishes to start
93 * the instance. Multitable protocols should lock their tables here.
95 * Result: new protocol state
97 int start(struct proto
*p
)
101 * shutdown - request instance shutdown
102 * @p: protocol instance
104 * The stop() hook is called by the core when it wishes to shut
105 * the instance down for some reason.
107 * Returns: new protocol state
109 int shutdown(struct proto
*p
)
113 * cleanup - request instance cleanup
114 * @p: protocol instance
116 * The cleanup() hook is called by the core when the protocol became
117 * hungry/down, i.e. all protocol ahooks and routes are flushed.
118 * Multitable protocols should unlock their tables here.
120 void cleanup(struct proto
*p
)
124 * get_status - get instance status
125 * @p: protocol instance
126 * @buf: buffer to be filled with the status string
128 * This hook is called by the core if it wishes to obtain an brief one-line user friendly
129 * representation of the status of the instance to be printed by the <cf/show protocols/
132 void get_status(struct proto
*p
, byte
*buf
)
136 * get_route_info - get route information
138 * @buf: buffer to be filled with the resulting string
139 * @attrs: extended attributes of the route
141 * This hook is called to fill the buffer @buf with a brief user friendly
142 * representation of metrics of a route belonging to this protocol.
144 void get_route_info(rte
*e
, byte
*buf
, ea_list
*attrs
)
148 * get_attr - get attribute information
149 * @a: an extended attribute
150 * @buf: buffer to be filled with attribute information
151 * @buflen: a length of the @buf parameter
153 * The get_attr() hook is called by the core to obtain a user friendly
154 * representation of an extended route attribute. It can either leave
155 * the whole conversion to the core (by returning %GA_UNKNOWN), fill
156 * in only attribute name (and let the core format the attribute value
157 * automatically according to the type field; by returning %GA_NAME)
158 * or doing the whole conversion (used in case the value requires extra
159 * care; return %GA_FULL).
161 int get_attr(eattr
*a
, byte
*buf
, int buflen
)
165 * if_notify - notify instance about interface changes
166 * @p: protocol instance
167 * @flags: interface change flags
168 * @i: the interface in question
170 * This hook is called whenever any network interface changes its status.
171 * The change is described by a combination of status bits (%IF_CHANGE_xxx)
172 * in the @flags parameter.
174 void if_notify(struct proto
*p
, unsigned flags
, struct iface
*i
)
178 * ifa_notify - notify instance about interface address changes
179 * @p: protocol instance
180 * @flags: address change flags
181 * @a: the interface address
183 * This hook is called to notify the protocol instance about an interface
184 * acquiring or losing one of its addresses. The change is described by
185 * a combination of status bits (%IF_CHANGE_xxx) in the @flags parameter.
187 void ifa_notify(struct proto
*p
, unsigned flags
, struct ifa
*a
)
191 * rt_notify - notify instance about routing table change
192 * @p: protocol instance
193 * @channel: notifying channel
194 * @net: a network entry
195 * @new: new route for the network
196 * @old: old route for the network
197 * @attrs: extended attributes associated with the @new entry
199 * The rt_notify() hook is called to inform the protocol instance about
200 * changes in the connected routing table @table, that is a route @old
201 * belonging to network @net being replaced by a new route @new with
202 * extended attributes @attrs. Either @new or @old or both can be %NULL
203 * if the corresponding route doesn't exist.
205 * If the type of route announcement is RA_OPTIMAL, it is an
206 * announcement of optimal route change, @new stores the new optimal
207 * route and @old stores the old optimal route.
209 * If the type of route announcement is RA_ANY, it is an announcement
210 * of any route change, @new stores the new route and @old stores the
211 * old route from the same protocol.
213 * @p->accept_ra_types specifies which kind of route announcements
214 * protocol wants to receive.
216 void rt_notify(struct proto
*p
, net
*net
, rte
*new, rte
*old
, ea_list
*attrs
)
220 * neigh_notify - notify instance about neighbor status change
221 * @neigh: a neighbor cache entry
223 * The neigh_notify() hook is called by the neighbor cache whenever
224 * a neighbor changes its state, that is it gets disconnected or a
225 * sticky neighbor gets connected.
227 void neigh_notify(neighbor
*neigh
)
231 * make_tmp_attrs - convert embedded attributes to temporary ones
233 * @pool: linear pool to allocate attribute memory in
235 * This hook is called by the routing table functions if they need
236 * to convert the protocol attributes embedded directly in the &rte
237 * to temporary extended attributes in order to distribute them
238 * to other protocols or to filters. make_tmp_attrs() creates
239 * an &ea_list in the linear pool @pool, fills it with values of the
240 * temporary attributes and returns a pointer to it.
242 ea_list
*make_tmp_attrs(rte
*e
, struct linpool
*pool
)
246 * store_tmp_attrs - convert temporary attributes to embedded ones
248 * @attrs: temporary attributes to be converted
250 * This hook is an exact opposite of make_tmp_attrs() -- it takes
251 * a list of extended attributes and converts them to attributes
252 * embedded in the &rte corresponding to this protocol.
254 * You must be prepared for any of the attributes being missing
255 * from the list and use default values instead.
257 void store_tmp_attrs(rte
*e
, ea_list
*attrs
)
261 * preexport - pre-filtering decisions before route export
262 * @p: protocol instance the route is going to be exported to
263 * @e: the route in question
264 * @attrs: extended attributes of the route
265 * @pool: linear pool for allocation of all temporary data
267 * The preexport() hook is called as the first step of a exporting
268 * a route from a routing table to the protocol instance. It can modify
269 * route attributes and force acceptance or rejection of the route before
270 * the user-specified filters are run. See rte_announce() for a complete description
271 * of the route distribution process.
273 * The standard use of this hook is to reject routes having originated
274 * from the same instance and to set default values of the protocol's metrics.
276 * Result: 1 if the route has to be accepted, -1 if rejected and 0 if it
277 * should be passed to the filters.
279 int preexport(struct proto
*p
, rte
**e
, ea_list
**attrs
, struct linpool
*pool
)
283 * rte_recalculate - prepare routes for comparison
284 * @table: a routing table
285 * @net: a network entry
286 * @new: new route for the network
287 * @old: old route for the network
288 * @old_best: old best route for the network (may be NULL)
290 * This hook is called when a route change (from @old to @new for a
291 * @net entry) is propagated to a @table. It may be used to prepare
292 * routes for comparison by rte_better() in the best route
293 * selection. @new may or may not be in @net->routes list,
296 * Result: 1 if the ordering implied by rte_better() changes enough
297 * that full best route calculation have to be done, 0 otherwise.
299 int rte_recalculate(struct rtable
*table
, struct network
*net
, struct rte
*new, struct rte
*old
, struct rte
*old_best
)
303 * rte_better - compare metrics of two routes
304 * @new: the new route
305 * @old: the original route
307 * This hook gets called when the routing table contains two routes
308 * for the same network which have originated from different instances
309 * of a single protocol and it wants to select which one is preferred
310 * over the other one. Protocols usually decide according to route metrics.
312 * Result: 1 if @new is better (more preferred) than @old, 0 otherwise.
314 int rte_better(rte
*new, rte
*old
)
318 * rte_same - compare two routes
322 * The rte_same() hook tests whether the routes @e1 and @e2 belonging
323 * to the same protocol instance have identical contents. Contents of
324 * &rta, all the extended attributes and &rte preference are checked
325 * by the core code, no need to take care of them here.
327 * Result: 1 if @e1 is identical to @e2, 0 otherwise.
329 int rte_same(rte
*e1
, rte
*e2
)
333 * rte_insert - notify instance about route insertion
337 * This hook is called whenever a &rte belonging to the instance
338 * is accepted for insertion to a routing table.
340 * Please avoid using this function in new protocols.
342 void rte_insert(net
*n
, rte
*e
)
346 * rte_remove - notify instance about route removal
350 * This hook is called whenever a &rte belonging to the instance
351 * is removed from a routing table.
353 * Please avoid using this function in new protocols.
355 void rte_remove(net
*n
, rte
*e
)