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.\"
| 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: head/lib/libkvm/kvm_getpcpu.3 235286 2012-05-11 20:06:46Z gjb $
| 29.\" $FreeBSD: head/lib/libkvm/kvm_getpcpu.3 249344 2013-04-10 20:26:53Z glebius $
|
30.\"
| 30.\"
|
31.Dd February 28, 2010
| 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"
| 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"
|
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
| 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
|
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
| 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
|
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 ,
| 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 ,
|
130.Xr kvm 3
| 161.Xr kvm 3 , 162.Xr counter 9 , 163.Xr zone 9
|
| |