1.\" $NetBSD: pcu.9,v 1.12 2017/03/17 10:09:24 wiz Exp $ 2.\" 3.\" Copyright (c) 2012-2014 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Mindaugas Rasiukevicius. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd May 16, 2017 31.Dt PCU 9 32.Os 33.Sh NAME 34.Nm pcu 35.Nd per-CPU unit (PCU) 36.Sh SYNOPSIS 37.In sys/pcu.h 38.Ft void 39.Fn pcu_load "const pcu_ops_t *pcu" 40.Ft void 41.Fn pcu_save "const pcu_ops_t *pcu" "lwp_t *l" 42.Ft void 43.Fn pcu_save_all "lwp_t *l" 44.Ft void 45.Fn pcu_discard "const pcu_ops_t *pcu" "lwp_t *l" "bool valid" 46.Ft void 47.Fn pcu_discard_all "lwp_t *l" 48.Ft bool 49.Fn pcu_valid_p "const pcu_ops_t *pcu" 50.\" ----- 51.Sh DESCRIPTION 52Per CPU Unit (PCU) is an interface to manage synchronization of any 53per-CPU context (unit) tied to an LWP context. 54Typical use of PCU is for "lazy-switch" synchronization of the FPU state. 55Each PCU has its operations defined by a 56.Vt pcu_ops_t 57structure. 58Members of 59.Vt pcu_ops_t 60are 61.Bd -literal 62 u_int pcu_id; 63 void (*pcu_state_save)(lwp_t *l); 64 void (*pcu_state_load)(lwp_t *l, u_int flags); 65 void (*pcu_state_release)(lwp_t *l); 66.Ed 67.Pp 68.Bl -tag 69.It Fn pcu_state_save 70Indicate to MD code that the PCU state on the current CPU should be 71saved into the given LWP's MD storage. 72.It Fn pcu_state_load 73Load PCU state from the given LWP's MD storage to the current CPU. 74The 75.Ar flags 76argument is a combination of one or more of the following: 77.Bl -tag -width PCU_VALIDXXX 78.It Dv PCU_VALID 79Indicate that the PCU state is considered valid and need not be initialized. 80This is the case if the PCU state was already used (and thus loaded) by the LWP 81and has not been discarded since. 82.It Dv PCU_REENABLE 83Indicate that a fault reoccurred while the PCU state is loaded, 84therefore PCU should be re-enabled. 85This happens if LWP is context switched to another CPU and then switched 86back to the original CPU while the state on that CPU has not been changed 87by other LWPs. 88It may also happen due to instruction "bouncing" on some architectures. 89.El 90.It Fn pcu_state_release 91Indicate to MD code that the PCU ownership by the LWP was released, 92therefore the next use of PCU on the LWP shall be detected and 93.Fn pcu_load 94be called to reacquire the ownership. 95For example, this would normally be the changing of a bit for a CPU to 96trap on the execution of one of the PCU's instructions. 97.El 98.\" ----- 99.Sh FUNCTIONS 100.Bl -tag -width pcu_save_allXXX 101.It Fn pcu_load 102Load or initialize the PCU state of the current LWP on the current CPU. 103.It Fn pcu_save 104Save the specified PCU state to the given LWP. 105.It Fn pcu_discard 106Discard the specified PCU state of the current LWP. 107The PCU state will be considered invalid, 108unless the "valid" parameter is set to true. 109.It Fn pcu_valid_p 110Return true if PCU state is considered valid. 111Generally, it always becomes "valid" when 112.Fn pcu_load 113is called by the LWP. 114Otherwise, return false. 115.It Fn pcu_discard_all 116Discard all PCU states of the given LWP; generally used by exec and exit. 117.It Fn pcu_save_all 118Save all PCU states of the given LWP; generally used during new LWP 119creation so that the PCU state of the parent could be copied. 120.El 121.\" ----- 122.Sh CODE REFERENCES 123.Nm 124is implemented within the file 125.Pa sys/kern/subr_pcu.c . 126.Sh HISTORY 127PCU first appeared in 128.Nx 6.0 . 129.Sh AUTHORS 130.An Mindaugas Rasiukevicius Aq Mt rmind@NetBSD.org 131