From f87454b0687474b91643265e4adc61d16b19e0b4 Mon Sep 17 00:00:00 2001 From: rmind Date: Sun, 2 Dec 2012 19:28:34 +0000 Subject: [PATCH] Add pcu(9) man page. --- share/man/man9/pcu.9 | 105 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 share/man/man9/pcu.9 diff --git a/share/man/man9/pcu.9 b/share/man/man9/pcu.9 new file mode 100644 index 000000000000..e7b3e136a7f8 --- /dev/null +++ b/share/man/man9/pcu.9 @@ -0,0 +1,105 @@ +.\" $NetBSD: pcu.9,v 1.1 2012/12/02 19:28:34 rmind Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Mindaugas Rasiukevicius. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 31, 2011 +.Dt PCU 9 +.Os +.Sh NAME +.Nm pcu +.Nd per-CPU unit (PCU) +.Sh SYNOPSIS +.In sys/pcu.h +.Ft void +.Fn pcu_load "const pcu_ops_t *pcu" +.Ft void +.Fn pcu_save "const pcu_ops_t *pcu" +.Ft void +.Fn pcu_save_all "lwp_t *l" +.Ft void +.Fn pcu_discard "const pcu_ops_t *pcu" +.Ft bool +.Fn pcu_used_p "const pcu_ops_t *pcu" +.\" ----- +.Sh DESCRIPTION +Per CPU Unit (PCU) is an interface to manage synchronization of any +per-CPU context (unit) tied to an LWP context. +Typical use of PCU is for "lazy-switch" synchronisation of FPU state. +Each PCU has its operations defined by a +.Vt pcu_ops_t +structure. +Members of +.Vt pcu_ops_t +are +.Bd -literal + u_int pcu_id; + void (*pcu_state_save)(lwp_t *l); + void (*pcu_state_load)(lwp_t *l, bool used); + void (*pcu_state_release)(lwp_t *l); +.Ed +.Pp +.Bl -tag -width compact +.It Fn pcu_state_save +save the current CPU's state into the given LWP's MD storage. +.It Fn pcu_state_load +load PCU state from the given LWP's MD storage to the current CPU. +The +.Ar used +argument is true if it is not the first time the LWP uses the PCU. +.It Fn pcu_state_release +indicate to MD code that the PCU ownership by the LWP was released, +therefore the next use of PCU on the LWP shall be detected and +.Fn pcu_load +be called to reacquire ownership. +For example, this would often be the changing of a bit for a CPU to +trap on the execution of one of the PCU's instructions. +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn pcu_load +Load (initialize) the PCU state of the current LWP on the current CPU. +.It Fn pcu_save +Save the PCU state to the given LWP. +.It Fn pcu_discard +Discard the PCU state of the current LWP. +.It Fn pcu_used_p +Return true if PCU was used (i.e. +.Fn pcu_load +was called) by the LWP. +Otherwise, return false. +.Fn pcu_save_all +save PCU state of the given LWP, so that it could be used later. +.El +.\" ----- +.Sh CODE REFERENCES +.Nm +is implemented within the file +.Pa sys/kern/subr_pcu.c . +.Sh HISTORY +PCU first appeared in +.Nx 6.0 .