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 April 11, 2013 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.Ft ssize_t 53.Fn kvm_read_zpcpu "kvm_t *kd" "void *buf" "u_long base" "size_t size" "int cpu" 54.Ft uint64_t 55.Fn kvm_counter_u64_fetch "kvm_t *kd" "u_long base" 56.Sh DESCRIPTION 57The 58.Fn kvm_dpcpu_setcpu , 59.Fn kvm_getmaxcpu , 60and 61.Fn kvm_getpcpu 62functions are used to access the per-CPU data of active processors in the 63kernel indicated by 64.Fa kd . 65Per-CPU storage comes in two flavours: data stored directly in a 66.Vt "struct pcpu" 67associated with each CPU, and dynamic per-CPU storage (DPCPU), in which a 68single kernel symbol refers to different data depending on what CPU it is 69accessed from. 70.Pp 71The 72.Fn kvm_getmaxcpu 73function returns the maximum number of CPUs supported by the kernel. 74.Pp 75The 76.Fn kvm_getpcpu 77function returns a buffer holding the per-CPU data for a single CPU. 78This buffer is described by the 79.Vt "struct pcpu" 80type. 81The caller is responsible for releasing the buffer via a call to 82.Xr free 3 83when it is no longer needed. 84If 85.Fa cpu 86is not active, then 87.Dv NULL 88is returned instead. 89.Pp 90The 91.Fn kvm_read_zpcpu 92function is used to obtain private per-CPU copy from a 93.Dv UMA_ZONE_PCPU 94.Xr zone 9 . 95It takes 96.Fa base 97argument as base address of an allocation and copyies 98.Fa size 99bytes into 100.Fa buf 101from the part of allocation that is private to 102.Fa cpu . 103.Pp 104The 105.Fn kvm_counter_u64_fetch 106function fetches value of a 107.Xr counter 9 108pointed by 109.Fa base 110address. 111.Pp 112Symbols for dynamic per-CPU data are accessed via 113.Xr kvm_nlist 3 114as with other symbols. 115.Nm libkvm 116maintains a notion of the "current CPU", set by 117.Xr kvm_dpcpu_setcpu , 118which defaults to 0. 119Once another CPU is selected, 120.Xr kvm_nlist 3 121will return pointers to that data on the appropriate CPU. 122.Sh CACHING 123.Fn kvm_getmaxcpu 124and 125.Fn kvm_getpcpu 126cache the nlist values for various kernel variables which are 127reused in successive calls. 128You may call either function with 129.Fa kd 130set to 131.Dv NULL 132to clear this cache. 133.Sh RETURN VALUES 134On success, the 135.Fn kvm_getmaxcpu 136function returns the maximum number of CPUs supported by the kernel. 137If an error occurs, 138it returns -1 instead. 139.Pp 140On success, the 141.Fn kvm_getpcpu 142function returns a pointer to an allocated buffer or 143.Dv NULL . 144If an error occurs, 145it returns -1 instead. 146.Pp 147On success, the 148.Fn kvm_dpcpu_setcpu 149call returns 0; if an error occurs, it returns -1 instead. 150.Pp 151On success, the 152.Fn kvm_read_zpcpu 153function returns number of bytes copied. 154If an error occurs, it returns -1 instead. 155.Pp 156If any function encounters an error, 157then an error message may be retrieved via 158.Xr kvm_geterr 3 . 159.Sh SEE ALSO 160.Xr free 3 , 161.Xr kvm 3 , 162.Xr counter 9 , 163.Xr zone 9 164