| pmc.k8.3 (145774) | pmc.k8.3 (147191) |
|---|---|
| 1.\" Copyright (c) 2003 Joseph Koshy. All rights reserved. | 1.\" Copyright (c) 2003-2005 Joseph Koshy. All rights reserved. |
| 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the --- 6 unchanged lines hidden (view full) --- 16.\" for any direct, indirect, incidental, special, exemplary, or consequential 17.\" damages (including, but not limited to, procurement of substitute goods 18.\" or services; loss of use, data, or profits; or business interruption) 19.\" however caused and on any theory of liability, whether in contract, strict 20.\" liability, or tort (including negligence or otherwise) arising in any way 21.\" out of the use of this software, even if advised of the possibility of 22.\" such damage. 23.\" | 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the --- 6 unchanged lines hidden (view full) --- 16.\" for any direct, indirect, incidental, special, exemplary, or consequential 17.\" damages (including, but not limited to, procurement of substitute goods 18.\" or services; loss of use, data, or profits; or business interruption) 19.\" however caused and on any theory of liability, whether in contract, strict 20.\" liability, or tort (including negligence or otherwise) arising in any way 21.\" out of the use of this software, even if advised of the possibility of 22.\" such damage. 23.\" |
| 24.\" $FreeBSD: head/lib/libpmc/pmc.3 145774 2005-05-01 14:11:49Z jkoshy $ | 24.\" $FreeBSD: head/lib/libpmc/pmc.3 147191 2005-06-09 19:45:09Z jkoshy $ |
| 25.\" 26.Dd Apr 15, 2005 27.Os 28.Dt PMC 3 29.Sh NAME 30.Nm pmc_allocate , 31.Nm pmc_attach , 32.Nm pmc_capabilities , 33.Nm pmc_configure_logfile , 34.Nm pmc_cpuinfo , 35.Nm pmc_detach , 36.Nm pmc_disable , 37.Nm pmc_enable , 38.Nm pmc_event_names_of_class , | 25.\" 26.Dd Apr 15, 2005 27.Os 28.Dt PMC 3 29.Sh NAME 30.Nm pmc_allocate , 31.Nm pmc_attach , 32.Nm pmc_capabilities , 33.Nm pmc_configure_logfile , 34.Nm pmc_cpuinfo , 35.Nm pmc_detach , 36.Nm pmc_disable , 37.Nm pmc_enable , 38.Nm pmc_event_names_of_class , |
| 39.Nm pmc_flush_logfile , |
|
| 39.Nm pmc_get_driver_stats , | 40.Nm pmc_get_driver_stats , |
| 41.Nm pmc_get_msr , |
|
| 40.Nm pmc_init , 41.Nm pmc_name_of_capability , 42.Nm pmc_name_of_class , 43.Nm pmc_name_of_cputype , 44.Nm pmc_name_of_event , 45.Nm pmc_name_of_mode , 46.Nm pmc_name_of_state , 47.Nm pmc_ncpu , 48.Nm pmc_npmc , 49.Nm pmc_pmcinfo , 50.Nm pmc_read , 51.Nm pmc_release , 52.Nm pmc_rw , 53.Nm pmc_set , 54.Nm pmc_start , 55.Nm pmc_stop , | 42.Nm pmc_init , 43.Nm pmc_name_of_capability , 44.Nm pmc_name_of_class , 45.Nm pmc_name_of_cputype , 46.Nm pmc_name_of_event , 47.Nm pmc_name_of_mode , 48.Nm pmc_name_of_state , 49.Nm pmc_ncpu , 50.Nm pmc_npmc , 51.Nm pmc_pmcinfo , 52.Nm pmc_read , 53.Nm pmc_release , 54.Nm pmc_rw , 55.Nm pmc_set , 56.Nm pmc_start , 57.Nm pmc_stop , |
| 56.Nm pmc_write , | |
| 57.Nm pmc_width , | 58.Nm pmc_width , |
| 58.Nm pmc_x86_get_msr | 59.Nm pmc_write , 60.Nm pmc_writelog |
| 59.Nd programming API for using hardware performance monitoring counters 60.Sh LIBRARY 61.Lb libpmc 62.Sh SYNOPSIS 63.In pmc.h 64.Ft int 65.Fo pmc_allocate 66.Fa "const char *eventspecifier" --- 7 unchanged lines hidden (view full) --- 74.Fa "pmc_id_t pmcid" 75.Fa "pid_t pid" 76.Fc 77.Ft int 78.Fn pmc_capabilities "pmc_id_t pmc" "uint32_t *caps" 79.Ft int 80.Fn pmc_configure_logfile "int fd" 81.Ft int | 61.Nd programming API for using hardware performance monitoring counters 62.Sh LIBRARY 63.Lb libpmc 64.Sh SYNOPSIS 65.In pmc.h 66.Ft int 67.Fo pmc_allocate 68.Fa "const char *eventspecifier" --- 7 unchanged lines hidden (view full) --- 76.Fa "pmc_id_t pmcid" 77.Fa "pid_t pid" 78.Fc 79.Ft int 80.Fn pmc_capabilities "pmc_id_t pmc" "uint32_t *caps" 81.Ft int 82.Fn pmc_configure_logfile "int fd" 83.Ft int |
| 82.Fn pmc_cpuinfo "const struct pmc_op_getcpuinfo **cpu_info" | 84.Fn pmc_cpuinfo "const struct pmc_cpuinfo **cpu_info" |
| 83.Ft int 84.Fo pmc_detach 85.Fa "pmc_id_t pmcid" 86.Fa "pid_t pid" 87.Fc 88.Ft int 89.Fn pmc_disable "uint32_t cpu" "int pmc" 90.Ft int 91.Fn pmc_enable "uint32_t cpu" "int pmc" 92.Ft int 93.Fo pmc_event_names_of_class 94.Fa "enum pmc_class cl" 95.Fa "const char ***eventnames" 96.Fa "int *nevents" 97.Fc 98.Ft int | 85.Ft int 86.Fo pmc_detach 87.Fa "pmc_id_t pmcid" 88.Fa "pid_t pid" 89.Fc 90.Ft int 91.Fn pmc_disable "uint32_t cpu" "int pmc" 92.Ft int 93.Fn pmc_enable "uint32_t cpu" "int pmc" 94.Ft int 95.Fo pmc_event_names_of_class 96.Fa "enum pmc_class cl" 97.Fa "const char ***eventnames" 98.Fa "int *nevents" 99.Fc 100.Ft int |
| 99.Fn pmc_get_driver_stats "struct pmc_op_getdriverstats *gms" | 101.Fn pmc_flush_logfile "void" |
| 100.Ft int | 102.Ft int |
| 103.Fn pmc_get_driver_stats "struct pmc_driverstats *gms" 104.Ft int 105.Fn pmc_get_msr "pmc_id_t pmc" "uint32_t *msr" 106.Ft int |
|
| 101.Fn pmc_init "void" 102.Ft "const char *" 103.Fn pmc_name_of_capability "enum pmc_caps pc" 104.Ft "const char *" 105.Fn pmc_name_of_class "enum pmc_class pc" 106.Ft "const char *" 107.Fn pmc_name_of_cputype "enum pmc_cputype ct" 108.Ft "const char *" --- 4 unchanged lines hidden (view full) --- 113.Fn pmc_name_of_mode "enum pmc_mode pm" 114.Ft "const char *" 115.Fn pmc_name_of_state "enum pmc_state ps" 116.Ft int 117.Fn pmc_ncpu "void" 118.Ft int 119.Fn pmc_npmc "uint32_t cpu" 120.Ft int | 107.Fn pmc_init "void" 108.Ft "const char *" 109.Fn pmc_name_of_capability "enum pmc_caps pc" 110.Ft "const char *" 111.Fn pmc_name_of_class "enum pmc_class pc" 112.Ft "const char *" 113.Fn pmc_name_of_cputype "enum pmc_cputype ct" 114.Ft "const char *" --- 4 unchanged lines hidden (view full) --- 119.Fn pmc_name_of_mode "enum pmc_mode pm" 120.Ft "const char *" 121.Fn pmc_name_of_state "enum pmc_state ps" 122.Ft int 123.Fn pmc_ncpu "void" 124.Ft int 125.Fn pmc_npmc "uint32_t cpu" 126.Ft int |
| 121.Fn pmc_pmcinfo "uint32_t cpu" "struct pmc_op_getpmcinfo **pmc_info" | 127.Fn pmc_pmcinfo "uint32_t cpu" "struct pmc_pmcinfo **pmc_info" |
| 122.Ft int 123.Fn pmc_read "pmc_id_t pmc" "pmc_value_t *value" 124.Ft int 125.Fn pmc_release "pmc_id_t pmc" 126.Ft int 127.Fn pmc_rw "pmc_id_t pmc" "pmc_value_t newvalue" "pmc_value_t *oldvaluep" 128.Ft int 129.Fn pmc_set "pmc_id_t pmc" "pmc_value_t value" 130.Ft int 131.Fn pmc_start "pmc_id_t pmc" 132.Ft int 133.Fn pmc_stop "pmc_id_t pmc" 134.Ft int 135.Fn pmc_write "pmc_id_t pmc" "pmc_value_t value" 136.Ft int | 128.Ft int 129.Fn pmc_read "pmc_id_t pmc" "pmc_value_t *value" 130.Ft int 131.Fn pmc_release "pmc_id_t pmc" 132.Ft int 133.Fn pmc_rw "pmc_id_t pmc" "pmc_value_t newvalue" "pmc_value_t *oldvaluep" 134.Ft int 135.Fn pmc_set "pmc_id_t pmc" "pmc_value_t value" 136.Ft int 137.Fn pmc_start "pmc_id_t pmc" 138.Ft int 139.Fn pmc_stop "pmc_id_t pmc" 140.Ft int 141.Fn pmc_write "pmc_id_t pmc" "pmc_value_t value" 142.Ft int |
| 137.Fn pmc_width "pmc_id_t pmc" "uint32_t *width" | 143.Fn pmc_writelog "uint32_t userdata" |
| 138.Ft int | 144.Ft int |
| 139.Fn pmc_x86_get_msr "int pmc" "uint32_t *msr" | 145.Fn pmc_width "pmc_id_t pmc" "uint32_t *width" |
| 140.Sh DESCRIPTION 141These functions implement a high-level library for using the 142system's hardware performance counters. 143.Pp 144PMCs are allocated using 145.Fn pmc_allocate , 146released using 147.Fn pmc_release --- 123 unchanged lines hidden (view full) --- 271.Fa width 272to the width of the PMC denoted by argument 273.Fa pmc . 274.Pp 275The 276.Fn pmc_configure_logfile 277function causes the 278.Xr hwpmc 4 | 146.Sh DESCRIPTION 147These functions implement a high-level library for using the 148system's hardware performance counters. 149.Pp 150PMCs are allocated using 151.Fn pmc_allocate , 152released using 153.Fn pmc_release --- 123 unchanged lines hidden (view full) --- 277.Fa width 278to the width of the PMC denoted by argument 279.Fa pmc . 280.Pp 281The 282.Fn pmc_configure_logfile 283function causes the 284.Xr hwpmc 4 |
| 279driver to log system wide performance data to file corresponding | 285driver to log performance data to file corresponding |
| 280to the process' file handle 281.Fa fd . | 286to the process' file handle 287.Fa fd . |
| 288If argument 289.Fa fd 290is -1, then any previously configured logging is reset 291and all data queued to be written are discarded. |
|
| 282.Pp | 292.Pp |
| 293The 294.Fn pmc_flush_logfile 295function will send all data queued inside the 296.Xr hwpmc 4 297driver to the configured log file before returning. 298The 299.Fn pmc_writelog 300function will append a log entry containing the argument 301.Fa userdata 302to the log file. 303.Pp |
|
| 283.Fn pmc_set 284configures an sampling PMC 285.Fa pmc 286to interrupt every 287.Fa value 288events. 289For counting PMCs, 290.Fn pmc_set --- 11 unchanged lines hidden (view full) --- 302.It SIGBUS 303When the 304.Xr hwpmc 4 305module is unloaded using 306.Xr kldunload 8 , 307processes that have PMCs allocated to them will be sent a 308SIGBUS signal. 309.It SIGIO | 304.Fn pmc_set 305configures an sampling PMC 306.Fa pmc 307to interrupt every 308.Fa value 309events. 310For counting PMCs, 311.Fn pmc_set --- 11 unchanged lines hidden (view full) --- 323.It SIGBUS 324When the 325.Xr hwpmc 4 326module is unloaded using 327.Xr kldunload 8 , 328processes that have PMCs allocated to them will be sent a 329SIGBUS signal. 330.It SIGIO |
| 310Attempting to read a PMC that is not currently attached to a running 311process will cause a SIGIO signal to be sent to the reader. | 331The 332.Xr hwpmc 4 333driver will send a PMC owning process a SIGIO signal if: 334.Bl -bullet 335.It 336If any process-mode PMC allocated by it loses all its 337target processes. 338.It 339If the driver encounters an error when writing log data to a 340configured log file. 341This error may be retrieved by a subsequent call to 342.Fn pmc_flush_logfile . |
| 312.El | 343.El |
| 344.El |
|
| 313.Ss CONVENIENCE FUNCTIONS 314.Fn pmc_ncpu 315returns the number of CPUs present in the system. 316.Pp 317.Fn pmc_npmc 318returns the number of PMCs supported on CPU 319.Fa cpu . 320.Fn pmc_cpuinfo 321sets argument 322.Fa cpu_info 323to point to a structure with information about the system's CPUs. | 345.Ss CONVENIENCE FUNCTIONS 346.Fn pmc_ncpu 347returns the number of CPUs present in the system. 348.Pp 349.Fn pmc_npmc 350returns the number of PMCs supported on CPU 351.Fa cpu . 352.Fn pmc_cpuinfo 353sets argument 354.Fa cpu_info 355to point to a structure with information about the system's CPUs. |
| 356Function |
|
| 324.Fn pmc_pmcinfo 325returns information about the current state of CPU 326.Fa cpu Ap s 327PMCs. | 357.Fn pmc_pmcinfo 358returns information about the current state of CPU 359.Fa cpu Ap s 360PMCs. |
| 361This function sets argument 362.Fa *pmc_info 363to point to a memory area allocated with 364.Xr calloc 3 . 365The caller is expected to 366.Fn free 367the area when done. |
|
| 328.Pp 329The functions 330.Fn pmc_name_of_capability , 331.Fn pmc_name_of_class , 332.Fn pmc_name_of_cputype , 333.Fn pmc_name_of_disposition , 334.Fn pmc_name_of_event , 335.Fn pmc_name_of_mode --- 29 unchanged lines hidden (view full) --- 365For these functions, 366.Fa cpu 367is the CPU number, and 368.Fa pmc 369is the index of the PMC to be operated on. 370Only the super-user is allowed to enable and disable PMCs. 371.Ss X86 ARCHITECTURE SPECIFIC API 372The | 368.Pp 369The functions 370.Fn pmc_name_of_capability , 371.Fn pmc_name_of_class , 372.Fn pmc_name_of_cputype , 373.Fn pmc_name_of_disposition , 374.Fn pmc_name_of_event , 375.Fn pmc_name_of_mode --- 29 unchanged lines hidden (view full) --- 405For these functions, 406.Fa cpu 407is the CPU number, and 408.Fa pmc 409is the index of the PMC to be operated on. 410Only the super-user is allowed to enable and disable PMCs. 411.Ss X86 ARCHITECTURE SPECIFIC API 412The |
| 373.Fn pmc_x86_get_msr | 413.Fn pmc_get_msr |
| 374function returns the processor model specific register number 375associated with 376.Fa pmc . 377Applications may use the x86 378.Sy RDPMC 379instruction to directly read the contents of the PMC. 380.Sh EVENT SPECIFIERS 381Event specifiers are strings comprising of an event name, followed by --- 2709 unchanged lines hidden (view full) --- 3091.Fa mode 3092argument passed in had an illegal value, or the event specification 3093.Fa ctrspec 3094was unrecognized for this cpu type. 3095.El 3096.Pp 3097Calls to 3098.Fn pmc_attach , | 414function returns the processor model specific register number 415associated with 416.Fa pmc . 417Applications may use the x86 418.Sy RDPMC 419instruction to directly read the contents of the PMC. 420.Sh EVENT SPECIFIERS 421Event specifiers are strings comprising of an event name, followed by --- 2709 unchanged lines hidden (view full) --- 3131.Fa mode 3132argument passed in had an illegal value, or the event specification 3133.Fa ctrspec 3134was unrecognized for this cpu type. 3135.El 3136.Pp 3137Calls to 3138.Fn pmc_attach , |
| 3139.Fn pmc_configure_logfile , |
|
| 3099.Fn pmc_detach , | 3140.Fn pmc_detach , |
| 3141.Fn pmc_disable , 3142.Fn pmc_enable , 3143.Fn pmc_get_driver_stats , 3144.Fn pmc_get_msr , 3145.Fn pmc_read , |
|
| 3100.Fn pmc_release , | 3146.Fn pmc_release , |
| 3147.Fn pmc_rw , 3148.Fn pmc_set , |
|
| 3101.Fn pmc_start , 3102.Fn pmc_stop , | 3149.Fn pmc_start , 3150.Fn pmc_stop , |
| 3103.Fn pmc_read , | |
| 3104.Fn pmc_write , | 3151.Fn pmc_write , |
| 3105.Fn pmc_rw , 3106.Fn pmc_set , 3107.Fn pmc_configure_logfile , 3108.Fn pmc_get_driver_stats , 3109.Fn pmc_enable , 3110.Fn pmc_disable , | |
| 3111and | 3152and |
| 3112.Fn pmc_x86_get_msr | 3153.Fn pmc_writelog |
| 3113may fail with the errors described in 3114.Xr hwpmc 4 . | 3154may fail with the errors described in 3155.Xr hwpmc 4 . |
| 3156.Pp 3157If a log file was configured using 3158.Fn pmc_configure_logfile 3159and the 3160.Xr hwpmc 4 3161driver encountered an error while logging data to it, then 3162logging will be stopped and a subsequent call to 3163.Fn pmc_flush_logfile 3164will fail with the error code seen by the 3165.Xr hwpmc 4 3166driver. |
|
| 3115.Sh SEE ALSO 3116.Xr modfind 2 , 3117.Xr modstat 2 , | 3167.Sh SEE ALSO 3168.Xr modfind 2 , 3169.Xr modstat 2 , |
| 3170.Xr calloc 3 , 3171.Xr pmclog 3 , |
|
| 3118.Xr hwpmc 4 , 3119.Xr pmccontrol 8 , 3120.Xr pmcreport 8 , 3121.Xr pmcstat 8 3122.Sh BUGS 3123The information returned by 3124.Fn pmc_cpuinfo , 3125.Fn pmc_ncpu 3126and possibly 3127.Fn pmc_npmc 3128should really be available all the time, through a better designed | 3172.Xr hwpmc 4 , 3173.Xr pmccontrol 8 , 3174.Xr pmcreport 8 , 3175.Xr pmcstat 8 3176.Sh BUGS 3177The information returned by 3178.Fn pmc_cpuinfo , 3179.Fn pmc_ncpu 3180and possibly 3181.Fn pmc_npmc 3182should really be available all the time, through a better designed |
| 3129interface. 3130.Pp 3131The API for 3132.Fn pmc_cpuinfo 3133and 3134.Fn pmc_pmcinfo 3135expose too much of the underlying | 3183interface and not just when |
| 3136.Xr hwpmc 4 | 3184.Xr hwpmc 4 |
| 3137driver's internals to userland. | 3185is present in the kernel. |