1.\" Copyright (c) 2008 Yahoo!, Inc. 2.\" All rights reserved. 3.\" Written by: John Baldwin <jhb@FreeBSD.org> 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. Neither the name of the author nor the names of any co-contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd February 28, 2010 32.Dt KVM_GETPCPU 3 33.Os 34.Sh NAME 35.Nm kvm_dpcpu_setcpu 36.Nm kvm_getmaxcpu , 37.Nm kvm_getpcpu 38.Nd access per-CPU data 39.Sh LIBRARY 40.Lb libkvm 41.Sh SYNOPSIS 42.In sys/param.h 43.In sys/pcpu.h 44.In sys/sysctl.h 45.In kvm.h 46.Ft int 47.Fn kvm_dpcpu_setcpu "kvm_t *kd" "u_int cpu" 48.Ft int 49.Fn kvm_getmaxcpu "kvm_t *kd" 50.Ft void * 51.Fn kvm_getpcpu "kvm_t *kd" "int cpu" 52.Sh DESCRIPTION 53The 54.Fn kvm_dpcpu_setcpu , 55.Fn kvm_getmaxcpu , 56and 57.Fn kvm_getpcpu 58functions are used to access the per-CPU data of active processors in the 59kernel indicated by 60.Fa kd . 61Per-CPU storage comes in two flavours: data stored directly in a 62.Vt "struct pcpu" 63associated with each CPU, and dynamic per-CPU storage (DPCPU), in which a 64single kernel symbol refers to different data depending on what CPU it is 65accessed from. 66.Pp 67The 68.Fn kvm_getmaxcpu 69function returns the maximum number of CPUs supported by the kernel. 70.Pp 71The 72.Fn kvm_getpcpu 73function returns a buffer holding the per-CPU data for a single CPU. 74This buffer is described by the 75.Vt "struct pcpu" 76type. 77The caller is responsible for releasing the buffer via a call to 78.Xr free 3 79when it is no longer needed. 80If 81.Fa cpu 82is not active, then 83.Dv NULL 84is returned instead. 85.Pp 86Symbols for dynamic per-CPU data are accessed via 87.Xr kvm_nlist 3 88as with other symbols. 89.Nm libkvm 90maintains a notion of the "current CPU", set by 91.Xr kvm_dpcpu_setcpu , 92which defaults to 0. 93Once another CPU is selected, 94.Xr kvm_nlist 3 95will return pointers to that data on the appropriate CPU. 96.Sh CACHING 97.Fn kvm_getmaxcpu 98and 99.Fn kvm_getpcpu 100cache the nlist values for various kernel variables which are 101reused in successive calls. 102You may call either function with 103.Fa kd 104set to 105.Dv NULL 106to clear this cache. 107.Sh RETURN VALUES 108On success, the 109.Fn kvm_getmaxcpu 110function returns the maximum number of CPUs supported by the kernel. 111If an error occurs, 112it returns -1 instead. 113.Pp 114On success, the 115.Fn kvm_getpcpu 116function returns a pointer to an allocated buffer or 117.Dv NULL . 118If an error occurs, 119it returns -1 instead. 120.Pp 121On success, the 122.Fn kvm_dpcpu_setcpu 123call returns 0; if an error occurs, it returns -1 instead. 124.Pp 125If any function encounters an error, 126then an error message may be retrieved via 127.Xr kvm_geterr 3 . 128.Sh SEE ALSO 129.Xr free 3 , 130.Xr kvm 3 131