xc_broadcast(9) [netbsd man page]

XCALL(9)						   BSD Kernel Developer's Manual						  XCALL(9)

NAME

     xcall, xc_broadcast, xc_unicast, xc_wait -- cross-call interface

SYNOPSIS

     #include <sys/xcall.h>

     typedef void (*xcfunc_t)(void *, void *);

     uint64_t
     xc_broadcast(u_int flags, xcfunc_t func, void *arg1, void *arg2);

     uint64_t
     xc_unicast(u_int flags, xcfunc_t func, void *arg1, void *arg2, struct cpu_info *ci);

     void
     xc_wait(uint64_t where);

DESCRIPTION

     The machine-independent xcall interface allows any CPU in the system to request that an arbitrary function be executed on any other CPU.

     Sometimes it is necessary to modify hardware state that is tied directly to individual CPUs (such as a CPU's local timer), and these updates
     can not be done remotely by another CPU.  The LWP requesting the update may be unable to guarantee that it will be running on the CPU where
     the update must occur, when the update occurs.

     Additionally, it is sometimes necessary to modify per-CPU software state from a remote CPU.  Where these update operations are so rare or the
     access to the per-CPU data so frequent that the cost of using locking or atomic operations to provide coherency is prohibitive, another way
     must be found.

     Cross calls help to solve these types of problem.	However, since this facility is heavyweight, it is expected that it will not be used
     often.

     xcall provides a mechanism for making ``low priority'' cross calls.  The function to be executed runs on the remote CPU within a thread con-
     text, and not from a software interrupt, so it can ensure that it is not interrupting other code running on the CPU, and so has exclusive
     access to the CPU.  Keep in mind that unless disabled, it may cause a kernel preemption.

     xcall also provides a mechanism for making ``high priority'' cross calls.	The function to be executed runs on the remote CPU within a
     IPL_SOFTCLOCK software interrupt context, possibly interrupting other lower-priority code running on the CPU.

NOTES

     Functions being called should be relatively lightweight.  They may block on locks, but carefully and minimally, to not interfere with other
     cross calls in the system.

FUNCTIONS

     xc_broadcast(flags, func, arg1, arg2)
	      Call (*func)(arg1, arg2) on all CPUs in the system.  Return a uint64_t ``ticket'' to xc_wait() on for the cross-call to complete.
	      flags should be XC_HIGHPRI for a "high priority" call, and 0 for a "low priority" call.  xc_broadcast() should not be called from
	      interrupt context.

     xc_unicast(flags, func, arg1, arg2, ci)
	      Like xc_broadcast(), but call (*func)() on only the CPU indicated by ci.	xc_unicast() also returns a ``ticket''.

     xc_wait(where)
	      Wait on the ``ticket'' returned by a prior xc_broadcast() or xc_unicast() for the corresponding cross-call to complete.  xc_wait()
	      should be called from a thread context.

CODE REFERENCES

     The xcall interface is implemented within the file sys/kern/subr_xcall.c.

SEE ALSO

     kpreempt(9), percpu(9)

HISTORY

     The xcall interface first appeared in NetBSD 5.0.

AUTHORS

     Andrew Doran <ad@NetBSD.org>

BSD
								 October 24, 2011							       BSD

Check Out this Related Man Page

PERCPU(9)						   BSD Kernel Developer's Manual						 PERCPU(9)

NAME

     percpu, percpu_alloc, percpu_free, percpu_getref, percpu_putref, percpu_foreach -- per-CPU storage allocator

SYNOPSIS

     #include <sys/percpu.h>

     typedef void (*percpu_callback_t)(void *, void *, struct cpu_info *);

     percpu_t *
     percpu_alloc(size_t size);

     void
     percpu_free(percpu_t *pc, size_t size);

     void *
     percpu_getref(percpu_t *pc);

     void
     percpu_putref(percpu_t *pc);

     void
     percpu_foreach(percpu_t *pc, percpu_callback_t cb, void *arg);

DESCRIPTION

     The machine-independent percpu interface provides per-CPU, CPU-local memory reservations to kernel subsystems.  percpu_alloc(size) reserves
     on each CPU an independent memory region of size bytes that is local to that CPU, returning a handle (percpu_t) to those regions.	A thread
     may subsequently ask for a pointer, p, to the region held by the percpu_t on the thread's current CPU.  Until the thread relinquishes the
     pointer, or voluntarily sleeps, the thread may read or write the region at p without causing interprocessor memory synchronization.

FUNCTIONS

     percpu_alloc(size)
	      Call this in thread context to allocate size bytes of local storage on each CPU.	The storage is initialized with zeroes.  Treat
	      this as an expensive operation.  percpu_alloc() returns NULL on failure, and a handle for the per-CPU storage on success.

     percpu_free(pc, size)
	      Call this in thread context to return to the system the per-CPU storage held by pc.  size should match the size passed to
	      percpu_alloc().  When percpu_free() returns, pc is undefined.  Treat this as an expensive operation.

     percpu_getref(pc)
	      Disable preemption and return a pointer to the storage held by pc on the local CPU.  Use percpu_getref() in either thread or inter-
	      rupt context.  Follow each percpu_getref() call with a matching call to percpu_putref().

     percpu_putref(pc)
	      Indicate that the thread is finished with the pointer returned by the matching call to percpu_getref().  Re-enables preemption.

     percpu_foreach(pc, cb, arg)
	      On each CPU, for ci the corresponding struct cpu_info * and p the CPU-local storage held by pc, run (*cb)(p, arg, ci).  Call this in
	      thread context.  cb should be non-blocking and fast.  Do not rely on cb to be run on the CPUs in any particular order.

CODE REFERENCES

     The percpu interface is implemented within the file sys/kern/subr_percpu.c.

SEE ALSO

     atomic_ops(3), kmem(9), pcq(9), pool_cache(9), xcall(9)

HISTORY

     The percpu interface first appeared in NetBSD 6.0.

AUTHORS

     YAMAMOTO Takashi <yamt@NetBSD.org>

BSD
								 January 23, 2010							       BSD

Linux and UNIX Man Pages

xc_broadcast(9) [netbsd man page]

Check Out this Related Man Page