1*05859157Swiz.\" $NetBSD: callback.9,v 1.5 2010/12/02 12:54:13 wiz Exp $ 243533de2Srmind.\" 343533de2Srmind.\" Copyright (c) 2009 The NetBSD Foundation, Inc. 443533de2Srmind.\" All rights reserved. 543533de2Srmind.\" 643533de2Srmind.\" Redistribution and use in source and binary forms, with or without 743533de2Srmind.\" modification, are permitted provided that the following conditions 843533de2Srmind.\" are met: 943533de2Srmind.\" 1. Redistributions of source code must retain the above copyright 1043533de2Srmind.\" notice, this list of conditions and the following disclaimer. 1143533de2Srmind.\" 2. Redistributions in binary form must reproduce the above copyright 1243533de2Srmind.\" notice, this list of conditions and the following disclaimer in the 1343533de2Srmind.\" documentation and/or other materials provided with the distribution. 1443533de2Srmind.\" 1543533de2Srmind.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 1643533de2Srmind.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 1743533de2Srmind.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 1843533de2Srmind.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 1943533de2Srmind.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 2043533de2Srmind.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 2143533de2Srmind.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 2243533de2Srmind.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 2343533de2Srmind.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 2443533de2Srmind.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 2543533de2Srmind.\" POSSIBILITY OF SUCH DAMAGE. 2643533de2Srmind.\" 27823d48daSwiz.Dd October 28, 2009 2843533de2Srmind.Dt CALLBACK 9 2943533de2Srmind.Os 3043533de2Srmind.Sh NAME 3143533de2Srmind.Nm callback 3243533de2Srmind.Nd generic callback interface 3343533de2Srmind.Sh SYNOPSIS 3443533de2Srmind.In sys/callback.h 3543533de2Srmind.Ft void 3643533de2Srmind.Fn callback_head_init "struct callback_head *ch" "int ipl" 3743533de2Srmind.Ft void 3843533de2Srmind.Fn callback_head_destroy "struct callback_head *ch" 3943533de2Srmind.Ft void 4043533de2Srmind.Fn callback_register \ 4143533de2Srmind"struct callback_head *ch" "struct callback_entry *ce" "void *obj" \ 4243533de2Srmind"int (*fn)(struct callback_entry *, void *, void *)" 4343533de2Srmind.Ft void 4443533de2Srmind.Fn callback_unregister "struct callback_head *ch" "struct callback_entry *ce" 4543533de2Srmind.Ft int 4643533de2Srmind.Fn callback_run_roundrobin "struct callback_head *ch" "void *arg" 4743533de2Srmind.Sh DESCRIPTION 4843533de2SrmindThe generic 4943533de2Srmind.Nm callback 5043533de2Srmindinterface allows lower-level layer code to execute a registered function, 5143533de2Srmindor set of functions, from the higher-level layer. 5243533de2Srmind.Pp 5343533de2SrmindRegistered functions must return one of these constants: 5443533de2Srmind.Bl -tag -width Dv 5543533de2Srmind.It Dv CALLBACK_CHAIN_CONTINUE 5643533de2SrmindIndicates that the function call was successful. 5743533de2SrmindThe following functions in the chain will be called. 5843533de2Srmind.It Dv CALLBACK_CHAIN_ABORT 5943533de2SrmindIndicates a failure case in the function call. 6043533de2SrmindAny following functions in the chain will not be executed. 6143533de2Srmind.El 6243533de2Srmind.Sh FUNCTIONS 6343533de2SrmindThe callback structure 6443533de2Srmind.Vt callback_head 6543533de2Srmindshould be initialized and destroyed using the functions described below. 6643533de2SrmindThis structure contains the list of callback entries and other internal data. 6743533de2Srmind.Pp 6843533de2SrmindThe 6943533de2Srmind.Vt callback_entry 7043533de2Srmindstructure is an entry, normally associated with the higher-level object. 7143533de2SrmindIt contains the internal data of the callback interface. 7243533de2Srmind.Bl -tag -width compact 7343533de2Srmind.It Fn callback_head_init "ch" "ipl" 7443533de2SrmindInitialize the callback structure specified by 7543533de2Srmind.Fa ch . 7643533de2SrmindThe highest IPL at which this callback can be used is specified by 7743533de2Srmind.Fa ipl . 7843533de2Srmind.It Fn callback_head_destroy "ch" 7943533de2SrmindDestroy the callback structure specified by 8043533de2Srmind.Fa ch . 8143533de2SrmindThe caller must unregister all functions before destroying the callback structure. 8243533de2Srmind.It Fn callback_register "ch" "ce" "obj" "fn" 8343533de2SrmindRegister the callback function in the callback structure specified by 8443533de2Srmind.Fa ch . 8543533de2Srmind.Fa ce 8643533de2Srmindshould point to the entry structure of the callback object. 8743533de2SrmindThe callback object itself is specified by 8843533de2Srmind.Fa obj . 8943533de2SrmindThe function pointer is specified by 9043533de2Srmind.Fa fn . 9143533de2Srmind.It Fn callback_unregister "ch" "ce" 9243533de2SrmindUnregister the callback function from the structure specified by 9343533de2Srmind.Fa ch . 9443533de2SrmindThe entry should be passed as 9543533de2Srmind.Fa ce . 9643533de2SrmindThis function may block. 9743533de2Srmind.It Fn callback_run_roundrobin "ch" "arg" 9843533de2SrmindExecutes all functions registered in the callback 9943533de2Srmindstructure, specified by 10043533de2Srmind.Fa ch . 10143533de2SrmindThe functions are executed in round-robin fashion. 10243533de2SrmindThe value of 10343533de2Srmind.Fa arg 10443533de2Srmindwill be passed to the callback functions. 10559da3d1cSjoerg.El 10643533de2Srmind.Sh CODE REFERENCES 10743533de2SrmindThe 10843533de2Srmind.Nm 10943533de2Srmindinterface is implemented within the file 11043533de2Srmind.Pa sys/kern/subr_callback.c . 11143533de2Srmind.Sh SEE ALSO 11243533de2Srmind.Xr intro 9 113