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