diff --git a/lib/libpmc/pmc.amd.3 b/lib/libpmc/pmc.amd.3 index ee0aae26d42f..047b31aa78bb 100644 --- a/lib/libpmc/pmc.amd.3 +++ b/lib/libpmc/pmc.amd.3 @@ -1,793 +1,793 @@ .\" Copyright (c) 2003-2008 Joseph Koshy. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd 24 June, 2023 +.Dd June 24, 2023 .Dt PMC.AMD 3 .Os .Sh NAME .Nm pmc.amd .Nm pmc.k8 .Nd measurement events for .Tn AMD .Tn Athlon 64 (K8 family) CPUs .Sh LIBRARY .Lb libpmc .Sh SYNOPSIS .In pmc.h .Sh DESCRIPTION AMD K8 PMCs are present in the .Tn "AMD Athlon64" and .Tn "AMD Opteron" series of CPUs. They are documented in the .Rs .%B "BIOS and Kernel Developer's Guide for the AMD Athlon(tm) 64 and AMD Opteron Processors" .%N "Publication No. 26094" .%D "April 2004" .%Q "Advanced Micro Devices, Inc." .Re .Ss PMC Features AMD K8 PMCs are 48 bits wide. Each CPU contains 4 PMCs with the following capabilities: .Bl -column "PMC_CAP_INTERRUPT" "Support" .It Em Capability Ta Em Support .It PMC_CAP_CASCADE Ta \&No .It PMC_CAP_EDGE Ta Yes .It PMC_CAP_INTERRUPT Ta Yes .It PMC_CAP_INVERT Ta Yes .It PMC_CAP_READ Ta Yes .It PMC_CAP_PRECISE Ta \&No .It PMC_CAP_SYSTEM Ta Yes .It PMC_CAP_TAGGING Ta \&No .It PMC_CAP_THRESHOLD Ta Yes .It PMC_CAP_USER Ta Yes .It PMC_CAP_WRITE Ta Yes .El .Ss Event Qualifiers Event specifiers for AMD K8 PMCs can have the following optional qualifiers: .Bl -tag -width indent .It Li count= Ns Ar value Configure the counter to increment only if the number of configured events measured in a cycle is greater than or equal to .Ar value . .It Li edge Configure the counter to only count negated-to-asserted transitions of the conditions expressed by the other fields. In other words, the counter will increment only once whenever a given condition becomes true, irrespective of the number of clocks during which the condition remains true. .It Li inv Invert the sense of comparison when the .Dq Li count qualifier is present, making the counter to increment when the number of events per cycle is less than the value specified by the .Dq Li count qualifier. .It Li mask= Ns Ar qualifier Many event specifiers for AMD K8 PMCs need to be additionally qualified using a mask qualifier. These additional qualifiers are event-specific and are documented along with their associated event specifiers below. .It Li os Configure the PMC to count events happening at privilege level 0. .It Li usr Configure the PMC to count events occurring at privilege levels 1, 2 or 3. .El .Pp If neither of the .Dq Li os or .Dq Li usr qualifiers were specified, the default is to enable both. .Ss AMD K8 Event Specifiers The event specifiers supported on AMD K8 PMCs are: .Bl -tag -width indent .It Li k8-bu-cpu-clk-unhalted .Pq Event 76H Count the number of clock cycles when the CPU is not in the HLT or STPCLK states. .It Li k8-bu-fill-request-l2-miss Op Li ,mask= Ns Ar qualifier .Pq Event 7EH Count fill requests that missed in the L2 cache. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li dc-fill Count data cache fill requests. .It Li ic-fill Count instruction cache fill requests. .It Li tlb-reload Count TLB reloads. .El .Pp The default is to count all types of requests. .It Li k8-bu-fill-into-l2 Op Li ,mask= Ns Ar qualifier .Pq Event 7FH The number of lines written to and from the L2 cache. The event may be further qualified by using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li dirty-l2-victim Count lines written into L2 cache due to victim writebacks from the Icache or Dcache, TLB page table walks or hardware data prefetches. .It Li victim-from-l2 Count writebacks of dirty lines from L2 to the system. .El .It Li k8-bu-internal-l2-request Op Li ,mask= Ns Ar qualifier .Pq Event 7DH Count internally generated requests to the L2 cache. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li cancelled Count cancelled requests. .It Li dc-fill Count data cache fill requests. .It Li ic-fill Count instruction cache fill requests. .It Li tag-snoop Count tag snoop requests. .It Li tlb-reload Count TLB reloads. .El .Pp The default is to count all types of requests. .It Li k8-dc-access .Pq Event 40H Count data cache accesses including microcode scratch pad accesses. .It Li k8-dc-copyback Op Li ,mask= Ns Ar qualifier .Pq Event 44H Count data cache copyback operations. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li exclusive Count operations for lines in the .Dq exclusive state. .It Li invalid Count operations for lines in the .Dq invalid state. .It Li modified Count operations for lines in the .Dq modified state. .It Li owner Count operations for lines in the .Dq owner state. .It Li shared Count operations for lines in the .Dq shared state. .El .Pp The default is to count operations for lines in all the above states. .It Li k8-dc-dcache-accesses-by-locks Op Li ,mask= Ns Ar qualifier .Pq Event 4CH Count data cache accesses by lock instructions. This event is only available on processors of revision C or later vintage. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li accesses Count data cache accesses by lock instructions. .It Li misses Count data cache misses by lock instructions. .El .Pp The default is to count all accesses. .It Li k8-dc-dispatched-prefetch-instructions Op Li ,mask= Ns Ar qualifier .Pq Event 4BH Count the number of dispatched prefetch instructions. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li load Count load operations. .It Li nta Count non-temporal operations. .It Li store Count store operations. .El .Pp The default is to count all operations. .It Li k8-dc-l1-dtlb-miss-and-l2-dtlb-hit .Pq Event 45H Count L1 DTLB misses that are L2 DTLB hits. .It Li k8-dc-l1-dtlb-miss-and-l2-dtlb-miss .Pq Event 46H Count L1 DTLB misses that are also misses in the L2 DTLB. .It Li k8-dc-microarchitectural-early-cancel-of-an-access .Pq Event 49H Count microarchitectural early cancels of data cache accesses. .It Li k8-dc-microarchitectural-late-cancel-of-an-access .Pq Event 48H Count microarchitectural late cancels of data cache accesses. .It Li k8-dc-misaligned-data-reference .Pq Event 47H Count misaligned data references. .It Li k8-dc-miss .Pq Event 41H Count data cache misses. .It Li k8-dc-one-bit-ecc-error Op Li ,mask= Ns Ar qualifier .Pq Event 4AH Count one bit ECC errors found by the scrubber. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li scrubber Count scrubber detected errors. .It Li piggyback Count piggyback scrubber errors. .El .Pp The default is to count both kinds of errors. .It Li k8-dc-refill-from-l2 Op Li ,mask= Ns Ar qualifier .Pq Event 42H Count data cache refills from L2 cache. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li exclusive Count operations for lines in the .Dq exclusive state. .It Li invalid Count operations for lines in the .Dq invalid state. .It Li modified Count operations for lines in the .Dq modified state. .It Li owner Count operations for lines in the .Dq owner state. .It Li shared Count operations for lines in the .Dq shared state. .El .Pp The default is to count operations for lines in all the above states. .It Li k8-dc-refill-from-system Op Li ,mask= Ns Ar qualifier .Pq Event 43H Count data cache refills from system memory. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li exclusive Count operations for lines in the .Dq exclusive state. .It Li invalid Count operations for lines in the .Dq invalid state. .It Li modified Count operations for lines in the .Dq modified state. .It Li owner Count operations for lines in the .Dq owner state. .It Li shared Count operations for lines in the .Dq shared state. .El .Pp The default is to count operations for lines in all the above states. .It Li k8-fp-cycles-with-no-fpu-ops-retired .Pq Event 01H Count cycles when no FPU ops were retired. This event is supported in revision B and later CPUs. .It Li k8-fp-dispatched-fpu-fast-flag-ops .Pq Event 02H Count dispatched FPU ops that use the fast flag interface. This event is supported in revision B and later CPUs. .It Li k8-fp-dispatched-fpu-ops Op Li ,mask= Ns Ar qualifier .Pq Event 00H Count the number of dispatched FPU ops. This event is supported in revision B and later CPUs. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li add-pipe-excluding-junk-ops Count add pipe ops excluding junk ops. .It Li add-pipe-junk-ops Count junk ops in the add pipe. .It Li multiply-pipe-excluding-junk-ops Count multiply pipe ops excluding junk ops. .It Li multiply-pipe-junk-ops Count junk ops in the multiply pipe. .It Li store-pipe-excluding-junk-ops Count store pipe ops excluding junk ops .It Li store-pipe-junk-ops Count junk ops in the store pipe. .El .Pp The default is to count all types of ops. .It Li k8-fr-decoder-empty .Pq Event D0H Count cycles when there was nothing to dispatch (i.e., the decoder was empty). .It Li k8-fr-dispatch-stall-for-segment-load .Pq Event D4H Count dispatch stalls for segment loads. .It Li k8-fr-dispatch-stall-for-serialization .Pq Event D3H Count dispatch stalls for serialization. .It Li k8-fr-dispatch-stall-from-branch-abort-to-retire .Pq Event D2H Count dispatch stalls from branch abort to retiral. .It Li k8-fr-dispatch-stall-when-fpu-is-full .Pq Event D7H Count dispatch stalls when the FPU is full. .It Li k8-fr-dispatch-stall-when-ls-is-full .Pq Event D8H Count dispatch stalls when the load/store unit is full. .It Li k8-fr-dispatch-stall-when-reorder-buffer-is-full .Pq Event D5H Count dispatch stalls when the reorder buffer is full. .It Li k8-fr-dispatch-stall-when-reservation-stations-are-full .Pq Event D6H Count dispatch stalls when reservation stations are full. .It Li k8-fr-dispatch-stall-when-waiting-far-xfer-or-resync-branch-pending .Pq Event DAH Count dispatch stalls when a far control transfer or a resync branch is pending. .It Li k8-fr-dispatch-stall-when-waiting-for-all-to-be-quiet .Pq Event D9H Count dispatch stalls when waiting for all to be quiet. .\" XXX What does "waiting for all to be quiet" mean? .It Li k8-fr-dispatch-stalls .Pq Event D1H Count all dispatch stalls. .It Li k8-fr-fpu-exceptions Op Li ,mask= Ns Ar qualifier .Pq Event DBH Count FPU exceptions. This event is supported in revision B and later CPUs. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li sse-and-x87-microtraps Count SSE and x87 microtraps. .It Li sse-reclass-microfaults Count SSE reclass microfaults .It Li sse-retype-microfaults Count SSE retype microfaults .It Li x87-reclass-microfaults Count x87 reclass microfaults. .El .Pp The default is to count all types of exceptions. .It Li k8-fr-interrupts-masked-cycles .Pq Event CDH Count cycles when interrupts were masked (by CPU RFLAGS field IF was zero). .It Li k8-fr-interrupts-masked-while-pending-cycles .Pq Event CEH Count cycles while interrupts were masked while pending (i.e., cycles when INTR was asserted while CPU RFLAGS field IF was zero). .It Li k8-fr-number-of-breakpoints-for-dr0 .Pq Event DCH Count the number of breakpoints for DR0. .It Li k8-fr-number-of-breakpoints-for-dr1 .Pq Event DDH Count the number of breakpoints for DR1. .It Li k8-fr-number-of-breakpoints-for-dr2 .Pq Event DEH Count the number of breakpoints for DR2. .It Li k8-fr-number-of-breakpoints-for-dr3 .Pq Event DFH Count the number of breakpoints for DR3. .It Li k8-fr-retired-branches .Pq Event C2H Count retired branches including exceptions and interrupts. .It Li k8-fr-retired-branches-mispredicted .Pq Event C3H Count mispredicted retired branches. .It Li k8-fr-retired-far-control-transfers .Pq Event C6H Count retired far control transfers (which are always mispredicted). .It Li k8-fr-retired-fastpath-double-op-instructions Op Li ,mask= Ns Ar qualifier .Pq Event CCH Count retired fastpath double op instructions. This event is supported in revision B and later CPUs. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li low-op-pos-0 Count instructions with the low op in position 0. .It Li low-op-pos-1 Count instructions with the low op in position 1. .It Li low-op-pos-2 Count instructions with the low op in position 2. .El .Pp The default is to count all types of instructions. .It Li k8-fr-retired-fpu-instructions Op Li ,mask= Ns Ar qualifier .Pq Event CBH Count retired FPU instructions. This event is supported in revision B and later CPUs. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li mmx-3dnow Count MMX and 3DNow!\& instructions. .It Li packed-sse-sse2 Count packed SSE and SSE2 instructions. .It Li scalar-sse-sse2 Count scalar SSE and SSE2 instructions .It Li x87 Count x87 instructions. .El .Pp The default is to count all types of instructions. .It Li k8-fr-retired-near-returns .Pq Event C8H Count retired near returns. .It Li k8-fr-retired-near-returns-mispredicted .Pq Event C9H Count mispredicted near returns. .It Li k8-fr-retired-resyncs .Pq Event C7H Count retired resyncs (non-control transfer branches). .It Li k8-fr-retired-taken-branches .Pq Event C4H Count retired taken branches. .It Li k8-fr-retired-taken-branches-mispredicted .Pq Event C5H Count retired taken branches that were mispredicted. .It Li k8-fr-retired-taken-branches-mispredicted-by-addr-miscompare .Pq Event CAH Count retired taken branches that were mispredicted only due to an address miscompare. .It Li k8-fr-retired-taken-hardware-interrupts .Pq Event CFH Count retired taken hardware interrupts. .It Li k8-fr-retired-uops .Pq Event C1H Count retired uops. .It Li k8-fr-retired-x86-instructions .Pq Event C0H Count retired x86 instructions including exceptions and interrupts. .It Li k8-ic-fetch .Pq Event 80H Count instruction cache fetches. .It Li k8-ic-instruction-fetch-stall .Pq Event 87H Count cycles in stalls due to instruction fetch. .It Li k8-ic-l1-itlb-miss-and-l2-itlb-hit .Pq Event 84H Count L1 ITLB misses that are L2 ITLB hits. .It Li k8-ic-l1-itlb-miss-and-l2-itlb-miss .Pq Event 85H Count ITLB misses that miss in both L1 and L2 ITLBs. .It Li k8-ic-microarchitectural-resync-by-snoop .Pq Event 86H Count microarchitectural resyncs caused by snoops. .It Li k8-ic-miss .Pq Event 81H Count instruction cache misses. .It Li k8-ic-refill-from-l2 .Pq Event 82H Count instruction cache refills from L2 cache. .It Li k8-ic-refill-from-system .Pq Event 83H Count instruction cache refills from system memory. .It Li k8-ic-return-stack-hits .Pq Event 88H Count hits to the return stack. .It Li k8-ic-return-stack-overflow .Pq Event 89H Count overflows of the return stack. .It Li k8-ls-buffer2-full .Pq Event 23H Count load/store buffer2 full events. .It Li k8-ls-locked-operation Op Li ,mask= Ns Ar qualifier .Pq Event 24H Count locked operations. For revision C and later CPUs, the following qualifiers are supported: .Pp .Bl -tag -width indent -compact .It Li cycles-in-request Count the number of cycles in the lock request/grant stage. .It Li cycles-to-complete Count the number of cycles a lock takes to complete once it is non-speculative and is the older load/store operation. .It Li locked-instructions Count the number of lock instructions executed. .El .Pp The default is to count the number of lock instructions executed. .It Li k8-ls-microarchitectural-late-cancel .Pq Event 25H Count microarchitectural late cancels of operations in the load/store unit. .It Li k8-ls-microarchitectural-resync-by-self-modifying-code .Pq Event 21H Count microarchitectural resyncs caused by self-modifying code. .It Li k8-ls-microarchitectural-resync-by-snoop .Pq Event 22H Count microarchitectural resyncs caused by snoops. .It Li k8-ls-retired-cflush-instructions .Pq Event 26H Count retired CFLUSH instructions. .It Li k8-ls-retired-cpuid-instructions .Pq Event 27H Count retired CPUID instructions. .It Li k8-ls-segment-register-load Op Li ,mask= Ns Ar qualifier .Pq Event 20H Count segment register loads. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Bl -tag -width indent -compact .It Li cs Count CS register loads. .It Li ds Count DS register loads. .It Li es Count ES register loads. .It Li fs Count FS register loads. .It Li gs Count GS register loads. .\" .It Li hs .\" Count HS register loads. .\" XXX "HS" register? .It Li ss Count SS register loads. .El .Pp The default is to count all types of loads. .It Li k8-nb-ht-bus0-bandwidth Op Li ,mask= Ns Ar qualifier .It Li k8-nb-ht-bus1-bandwidth Op Li ,mask= Ns Ar qualifier .It Li k8-nb-ht-bus2-bandwidth Op Li ,mask= Ns Ar qualifier .Pq Events F6H, F7H and F8H respectively Count events on the HyperTransport(tm) buses. These events may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li buffer-release Count buffer release messages sent. .It Li command Count command messages sent. .It Li data Count data messages sent. .It Li nop Count nop messages sent. .El .Pp The default is to count all types of messages. .It Li k8-nb-memory-controller-bypass-saturation Op Li ,mask= Ns Ar qualifier .Pq Event E4H Count memory controller bypass counter saturation events. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li dram-controller-interface-bypass Count DRAM controller interface bypass. .It Li dram-controller-queue-bypass Count DRAM controller queue bypass. .It Li memory-controller-hi-pri-bypass Count memory controller high priority bypasses. .It Li memory-controller-lo-pri-bypass Count memory controller low priority bypasses. .El .It Li k8-nb-memory-controller-dram-slots-missed .Pq Event E2H Count memory controller DRAM command slots missed (in MemClks). .It Li k8-nb-memory-controller-page-access-event Op Li ,mask= Ns Ar qualifier .Pq Event E0H Count memory controller page access events. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li page-conflict Count page conflicts. .It Li page-hit Count page hits. .It Li page-miss Count page misses. .El .Pp The default is to count all types of events. .It Li k8-nb-memory-controller-page-table-overflow .Pq Event E1H Count memory control page table overflow events. .It Li k8-nb-memory-controller-turnaround Op Li ,mask= Ns Ar qualifier .Pq Event E3H Count memory control turnaround events. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .\" XXX doc is unclear whether these are cycle counts or event counts .It Li dimm-turnaround Count DIMM turnarounds. .It Li read-to-write-turnaround Count read to write turnarounds. .It Li write-to-read-turnaround Count write to read turnarounds. .El .Pp The default is to count all types of events. .It Li k8-nb-probe-result Op Li ,mask= Ns Ar qualifier .Pq Event ECH Count probe events. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li probe-hit Count all probe hits. .It Li probe-hit-dirty-no-memory-cancel Count probe hits without memory cancels. .It Li probe-hit-dirty-with-memory-cancel Count probe hits with memory cancels. .It Li probe-miss Count probe misses. .El .It Li k8-nb-sized-commands Op Li ,mask= Ns Ar qualifier .Pq Event EBH Count sized commands issued. This event may be further qualified using .Ar qualifier , which is a .Ql + separated set of the following keywords: .Pp .Bl -tag -width indent -compact .It Li nonpostwrszbyte .It Li nonpostwrszdword .It Li postwrszbyte .It Li postwrszdword .It Li rdszbyte .It Li rdszdword .It Li rdmodwr .El .Pp The default is to count all types of commands. .El .Ss Event Name Aliases The following table shows the mapping between the PMC-independent aliases supported by .Lb libpmc and the underlying hardware events used. .Bl -column "branch-mispredicts" "Description" .It Em Alias Ta Em Event .It Li branches Ta Li k8-fr-retired-taken-branches .It Li branch-mispredicts Ta Li k8-fr-retired-taken-branches-mispredicted .It Li dc-misses Ta Li k8-dc-miss .It Li ic-misses Ta Li k8-ic-miss .It Li instructions Ta Li k8-fr-retired-x86-instructions .It Li interrupts Ta Li k8-fr-taken-hardware-interrupts .It Li unhalted-cycles Ta Li k8-bu-cpu-clk-unhalted .El .Sh SEE ALSO .Xr pmc 3 , .Xr pmc.atom 3 , .Xr pmc.core 3 , .Xr pmc.core2 3 , .Xr pmc.iaf 3 , .Xr pmc.soft 3 , .Xr pmc.tsc 3 , .Xr pmclog 3 , .Xr hwpmc 4 .Sh HISTORY The .Nm pmc library first appeared in .Fx 6.0 . .Sh AUTHORS The .Lb libpmc library was written by .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . diff --git a/lib/libusb/libusb.3 b/lib/libusb/libusb.3 index 43afa55380a8..fe07e86623c8 100644 --- a/lib/libusb/libusb.3 +++ b/lib/libusb/libusb.3 @@ -1,805 +1,805 @@ .\" .\" Copyright (c) 2009 Sylvestre Gallon .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd January, 26, 2023 +.Dd January 26, 2023 .Dt LIBUSB 3 .Os .Sh NAME .Nm libusb .Nd "USB access library" .Sh LIBRARY USB access library .Pq libusb, -lusb .Sh SYNOPSIS .In libusb.h .Sh DESCRIPTION The .Nm library contains interfaces for directly managing a usb device. The current implementation supports v1.0 of the libusb API. .Sh LIBRARY INITIALISATION AND DEINITIALISATION .Ft "const struct libusb_version *" .Fn libusb_get_version "void" This function returns version information about LibUSB. .Pp .Ft int .Fn libusb_init "libusb_context **ctx" Call this function before any other libusb v1.0 API function, to initialise a valid libusb v1.0 context. If the .Fa ctx argument is non-NULL, a pointer to the libusb context is stored at the given location. This function returns 0 upon success or LIBUSB_ERROR on failure. .Pp .Ft int .Fn libusb_init_context "libusb_context **ctx" "const struct libusb_init_option []" "int num_options" Call this function before any other libusb v1.0 API function, to initialise a valid libusb v1.0 context. If the .Fa ctx argument is non-NULL, a pointer to the libusb context is stored at the given location. Additional options, like the USB debug level, may be given using the second and third argument. If no options are needed, simply use libusb_init(). This function returns 0 upon success or a LIBUSB_ERROR value on failure. .Pp .Ft void .Fn libusb_exit "libusb_context *ctx" Deinitialise libusb. Must be called at the end of the application. Other libusb routines may not be called after this function. .Pp .Ft int .Fn libusb_has_capability "uint32_t capability" This function checks the runtime capabilities of .Nm . This function will return non-zero if the given .Fa capability is supported, 0 if it is not supported. The valid values for .Fa capability are: .Bl -tag -width LIBUSB_CAP -offset indent .It Va LIBUSB_CAP_HAS_CAPABILITY .Nm supports .Fn libusb_has_capability . .It Va LIBUSB_CAP_HAS_HOTPLUG .Nm supports hotplug notifications. .It Va LIBUSB_CAP_HAS_HID_ACCESS .Nm can access HID devices without requiring user intervention. .It Va LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER .Nm supports detaching of the default USB driver with .Fn libusb_detach_kernel_driver . .El .Pp .Ft const char * .Fn libusb_strerror "int code" Get the ASCII representation of the error given by the .Fa code argument. This function does not return NULL. .Pp .Ft const char * .Fn libusb_error_name "int code" Get the ASCII representation of the error enum given by the .Fa code argument. This function does not return NULL. .Pp .Ft void .Fn libusb_set_debug "libusb_context *ctx" "int level" Set the debug level to .Fa level . .Pp .Ft ssize_t .Fn libusb_get_device_list "libusb_context *ctx" "libusb_device ***list" Populate .Fa list with the list of usb devices available, adding a reference to each device in the list. All the list entries created by this function must have their reference counter decremented when you are done with them, and the list itself must be freed. This function returns the number of devices in the list or a LIBUSB_ERROR code. .Pp .Ft void .Fn libusb_free_device_list "libusb_device **list" "int unref_devices" Free the list of devices discovered by libusb_get_device_list. If .Fa unref_device is set to 1 all devices in the list have their reference counter decremented once. .Pp .Ft uint8_t .Fn libusb_get_bus_number "libusb_device *dev" Returns the number of the bus contained by the device .Fa dev . .Pp .Ft uint8_t .Fn libusb_get_port_number "libusb_device *dev" Returns the port number which the device given by .Fa dev is attached to. .Pp .Ft int .Fn libusb_get_port_numbers "libusb_device *dev" "uint8_t *buf" "uint8_t bufsize" Stores, in the buffer .Fa buf of size .Fa bufsize , the list of all port numbers from root for the device .Fa dev . .Pp .Ft int .Fn libusb_get_port_path "libusb_context *ctx" "libusb_device *dev" "uint8_t *buf" "uint8_t bufsize" Deprecated function equivalent to libusb_get_port_numbers. .Pp .Ft uint8_t .Fn libusb_get_device_address "libusb_device *dev" Returns the device_address contained by the device .Fa dev . .Pp .Ft enum libusb_speed .Fn libusb_get_device_speed "libusb_device *dev" Returns the wire speed at which the device is connected. See the LIBUSB_SPEED_XXX enums for more information. LIBUSB_SPEED_UNKNOWN is returned in case of unknown wire speed. .Pp .Ft int .Fn libusb_get_max_packet_size "libusb_device *dev" "unsigned char endpoint" Returns the wMaxPacketSize value on success, LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure. .Pp .Ft int .Fn libusb_get_max_iso_packet_size "libusb_device *dev" "unsigned char endpoint" Returns the packet size multiplied by the packet multiplier on success, LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist and LIBUSB_ERROR_OTHERS on other failure. .Pp .Ft libusb_device * .Fn libusb_ref_device "libusb_device *dev" Increment the reference counter of the device .Fa dev . .Pp .Ft void .Fn libusb_unref_device "libusb_device *dev" Decrement the reference counter of the device .Fa dev . .Pp .Ft int .Fn libusb_open "libusb_device *dev" "libusb_device_handle **devh" Open a device and obtain a device_handle. Returns 0 on success, LIBUSB_ERROR_NO_MEM on memory allocation problems, LIBUSB_ERROR_ACCESS on permissions problems, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on other errors. .Pp .Ft libusb_device_handle * .Fn libusb_open_device_with_vid_pid "libusb_context *ctx" "uint16_t vid" "uint16_t pid" A convenience function to open a device by vendor and product IDs .Fa vid and .Fa pid . Returns NULL on error. .Pp .Ft void .Fn libusb_close "libusb_device_handle *devh" Close a device handle. .Pp .Ft libusb_device * .Fn libusb_get_device "libusb_device_handle *devh" Get the device contained by devh. Returns NULL on error. .Pp .Ft int .Fn libusb_get_configuration "libusb_device_handle *devh" "int *config" Returns the value of the current configuration. Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on error. .Pp .Ft int .Fn libusb_set_configuration "libusb_device_handle *devh" "int config" Set the active configuration to .Fa config for the device contained by .Fa devh . This function returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested configuration does not exist, LIBUSB_ERROR_BUSY if the interfaces are currently claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_claim_interface "libusb_device_handle *devh" "int interface_number" Claim an interface in a given libusb_handle .Fa devh . This is a non-blocking function. It returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the requested interface does not exist, LIBUSB_ERROR_BUSY if a program or driver has claimed the interface, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_release_interface "libusb_device_handle *devh" "int interface_number" This function releases an interface. All the claimed interfaces on a device must be released before closing the device. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the interface was not claimed, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and LIBUSB_ERROR on failure. .Pp .Ft int .Fn libusb_set_interface_alt_setting "libusb_device_handle *dev" "int interface_number" "int alternate_setting" Activate an alternate setting for an interface. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the interface was not claimed or the requested setting does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_clear_halt "libusb_device_handle *devh" "unsigned char endpoint" Clear an halt/stall for a endpoint. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the endpoint does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_reset_device "libusb_device_handle *devh" Perform an USB port reset for an usb device. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if re-enumeration is required or if the device has been disconnected and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_check_connected "libusb_device_handle *devh" Test if the USB device is still connected. Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if it has been disconnected and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_kernel_driver_active "libusb_device_handle *devh" "int interface" Determine if a driver is active on a interface. Returns 0 if no kernel driver is active and 1 if a kernel driver is active, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_get_driver "libusb_device_handle *devh" "int interface" "char *name" "int namelen" or .Ft int .Fn libusb_get_driver_np "libusb_device_handle *devh" "int interface" "char *name" "int namelen" Copy the name of the driver attached to the given .Fa device and .Fa interface into the buffer .Fa name of length .Fa namelen . Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver is attached to the given interface and LIBUSB_ERROR_INVALID_PARAM if the interface does not exist. This function is non-portable. The buffer pointed to by .Fa name is only zero terminated on success. .Pp .Ft int .Fn libusb_detach_kernel_driver "libusb_device_handle *devh" "int interface" or .Ft int .Fn libusb_detach_kernel_driver_np "libusb_device_handle *devh" "int interface" Detach a kernel driver from an interface. This is needed to claim an interface already claimed by a kernel driver. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if no kernel driver was active, LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on failure. This function is non-portable. .Pp .Ft int .Fn libusb_attach_kernel_driver "libusb_device_handle *devh" "int interface" Re-attach an interface kernel driver that was previously detached. Returns 0 on success, LIBUSB_ERROR_INVALID_PARAM if the interface does not exist, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected, LIBUSB_ERROR_BUSY if the driver cannot be attached because the interface is claimed by a program or driver and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_set_auto_detach_kernel_driver "libusb_device_handle *devh" "int enable" This function enables automatic kernel interface driver detach when an interface is claimed. When the interface is restored the kernel driver is allowed to be re-attached. If the .Fa enable argument is non-zero the feature is enabled. Else disabled. Returns 0 on success and a LIBUSB_ERROR code on failure. .Sh USB DESCRIPTORS .Ft int .Fn libusb_get_device_descriptor "libusb_device *dev" "libusb_device_descriptor *desc" Get the USB device descriptor for the device .Fa dev . This is a non-blocking function. Returns 0 on success and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_get_active_config_descriptor "libusb_device *dev" "struct libusb_config_descriptor **config" Get the USB configuration descriptor for the active configuration. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the device is in an unconfigured state and a LIBUSB_ERROR code on error. .Pp .Ft int .Fn libusb_get_config_descriptor "libusb_device *dev" "uint8_t config_index" "libusb_config_descriptor **config" Get a USB configuration descriptor based on its index .Fa idx . Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and a LIBUSB_ERROR code on error. .Pp .Ft int .Fn libusb_get_config_descriptor_by_value "libusb_device *dev" "uint8 bConfigurationValue" "libusb_config_descriptor **config" Get a USB configuration descriptor with a specific bConfigurationValue. This is a non-blocking function which does not send a request through the device. Returns 0 on success, LIBUSB_ERROR_NOT_FOUND if the configuration does not exist and a LIBUSB_ERROR code on failure. .Pp .Ft void .Fn libusb_free_config_descriptor "libusb_config_descriptor *config" Free a configuration descriptor. .Pp .Ft int .Fn libusb_get_string_descriptor "libusb_device_handle *devh" "uint8_t desc_idx" "uint16_t langid" "unsigned char *data" "int length" Retrieve a string descriptor in raw format. Returns the number of bytes actually transferred on success or a negative LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_get_string_descriptor_ascii "libusb_device_handle *devh" "uint8_t desc_idx" "unsigned char *data" "int length" Retrieve a string descriptor in C style ASCII. Returns the positive number of bytes in the resulting ASCII string on success and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_parse_ss_endpoint_comp "const void *buf" "int len" "libusb_ss_endpoint_companion_descriptor **ep_comp" This function parses the USB 3.0 endpoint companion descriptor in host endian format pointed to by .Fa buf and having a length of .Fa len . Typically these arguments are the extra and extra_length fields of the endpoint descriptor. On success the pointer to resulting descriptor is stored at the location given by .Fa ep_comp . Returns zero on success and a LIBUSB_ERROR code on failure. On success the parsed USB 3.0 endpoint companion descriptor must be freed using the libusb_free_ss_endpoint_comp function. .Pp .Ft void .Fn libusb_free_ss_endpoint_comp "libusb_ss_endpoint_companion_descriptor *ep_comp" This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor given by .Fa ep_comp . .Pp .Ft int .Fn libusb_get_ss_endpoint_companion_descriptor "struct libusb_context *ctx" "const struct libusb_endpoint_descriptor *endpoint" "struct libusb_ss_endpoint_companion_descriptor **ep_comp" This function finds and parses the USB 3.0 endpoint companion descriptor given by .Fa endpoint . Returns zero on success and a LIBUSB_ERROR code on failure. On success the parsed USB 3.0 endpoint companion descriptor must be freed using the libusb_free_ss_endpoint_companion_descriptor function. .Pp .Ft void .Fn libusb_free_ss_endpoint_companion_descriptor "struct libusb_ss_endpoint_companion_descriptor *ep_comp" This function is NULL safe and frees a parsed USB 3.0 endpoint companion descriptor given by .Fa ep_comp . .Pp .Ft int .Fn libusb_get_bos_descriptor "libusb_device_handle *handle" "struct libusb_bos_descriptor **bos" This function queries the USB device given by .Fa handle and stores a pointer to a parsed BOS descriptor into .Fa bos . Returns zero on success and a LIBUSB_ERROR code on failure. On success the parsed BOS descriptor must be freed using the libusb_free_bos_descriptor function. .Pp .Ft int .Fn libusb_parse_bos_descriptor "const void *buf" "int len" "libusb_bos_descriptor **bos" This function parses a Binary Object Store, BOS, descriptor into host endian format pointed to by .Fa buf and having a length of .Fa len . On success the pointer to resulting descriptor is stored at the location given by .Fa bos . Returns zero on success and a LIBUSB_ERROR code on failure. On success the parsed BOS descriptor must be freed using the libusb_free_bos_descriptor function. .Pp .Ft void .Fn libusb_free_bos_descriptor "libusb_bos_descriptor *bos" This function is NULL safe and frees a parsed BOS descriptor given by .Fa bos . .Pp .Ft int .Fn libusb_get_usb_2_0_extension_descriptor "struct libusb_context *ctx" "struct libusb_bos_dev_capability_descriptor *dev_cap" "struct libusb_usb_2_0_extension_descriptor **usb_2_0_extension" This function parses the USB 2.0 extension descriptor from the descriptor given by .Fa dev_cap and stores a pointer to the parsed descriptor into .Fa usb_2_0_extension . Returns zero on success and a LIBUSB_ERROR code on failure. On success the parsed USB 2.0 extension descriptor must be freed using the libusb_free_usb_2_0_extension_descriptor function. .Pp .Ft void .Fn libusb_free_usb_2_0_extension_descriptor "struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension" This function is NULL safe and frees a parsed USB 2.0 extension descriptor given by .Fa usb_2_0_extension . .Pp .Ft int .Fn libusb_get_ss_usb_device_capability_descriptor "struct libusb_context *ctx" "struct libusb_bos_dev_capability_descriptor *dev_cap" "struct libusb_ss_usb_device_capability_descriptor **ss_usb_device_capability" This function parses the SuperSpeed device capability descriptor from the descriptor given by .Fa dev_cap and stores a pointer to the parsed descriptor into .Fa ss_usb_device_capability . Returns zero on success and a LIBUSB_ERROR code on failure. On success the parsed SuperSpeed device capability descriptor must be freed using the libusb_free_ss_usb_device_capability_descriptor function. .Pp .Ft void .Fn libusb_free_ss_usb_device_capability_descriptor "struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_capability" This function is NULL safe and frees a parsed SuperSpeed device capability descriptor given by .Fa ss_usb_device_capability . .Pp .Ft int .Fn libusb_get_container_id_descriptor "struct libusb_context *ctx" "struct libusb_bos_dev_capability_descriptor *dev_cap" "struct libusb_container_id_descriptor **container_id" This function parses the container ID descriptor from the descriptor given by .Fa dev_cap and stores a pointer to the parsed descriptor into .Fa container_id . Returns zero on success and a LIBUSB_ERROR code on failure. On success the parsed container ID descriptor must be freed using the libusb_free_container_id_descriptor function. .Pp .Ft void .Fn libusb_free_container_id_descriptor "struct libusb_container_id_descriptor *container_id" This function is NULL safe and frees a parsed container ID descriptor given by .Fa container_id . .Sh USB ASYNCHRONOUS I/O .Ft struct libusb_transfer * .Fn libusb_alloc_transfer "int iso_packets" Allocate a transfer with the number of isochronous packet descriptors specified by .Fa iso_packets . Returns NULL on error. .Pp .Ft void .Fn libusb_free_transfer "struct libusb_transfer *tr" Free a transfer. .Pp .Ft int .Fn libusb_submit_transfer "struct libusb_transfer *tr" This function will submit a transfer and returns immediately. Returns 0 on success, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on other failure. .Pp .Ft int .Fn libusb_cancel_transfer "struct libusb_transfer *tr" This function asynchronously cancels a transfer. Returns 0 on success and a LIBUSB_ERROR code on failure. .Sh USB SYNCHRONOUS I/O .Ft int .Fn libusb_control_transfer "libusb_device_handle *devh" "uint8_t bmRequestType" "uint8_t bRequest" "uint16_t wValue" "uint16_t wIndex" "unsigned char *data" "uint16_t wLength" "unsigned int timeout" Perform a USB control transfer. Returns the actual number of bytes transferred on success, in the range from and including zero up to and including .Fa wLength . On error a LIBUSB_ERROR code is returned, for example LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not supported, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and another LIBUSB_ERROR code on other failures. The LIBUSB_ERROR codes are all negative. .Pp .Ft int .Fn libusb_bulk_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" Perform an USB bulk transfer. A timeout value of zero means no timeout. The timeout value is given in milliseconds. Returns 0 on success, LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on other failure. .Pp .Ft int .Fn libusb_interrupt_transfer "struct libusb_device_handle *devh" "unsigned char endpoint" "unsigned char *data" "int length" "int *transferred" "unsigned int timeout" Perform an USB Interrupt transfer. A timeout value of zero means no timeout. The timeout value is given in milliseconds. Returns 0 on success, LIBUSB_ERROR_TIMEOUT if the transfer timed out, LIBUSB_ERROR_PIPE if the control request was not supported, LIBUSB_ERROR_OVERFLOW if the device offered more data, LIBUSB_ERROR_NO_DEVICE if the device has been disconnected and a LIBUSB_ERROR code on other failure. .Sh USB STREAMS SUPPORT .Ft int .Fn libusb_alloc_streams "libusb_device_handle *dev" "uint32_t num_streams" "unsigned char *endpoints" "int num_endpoints" This function verifies that the given number of streams using the given number of endpoints is allowed and allocates the resources needed to use so-called USB streams. Currently only a single stream per endpoint is supported to simplify the internals of LibUSB. This function returns 0 on success or a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_free_streams "libusb_device_handle *dev" "unsigned char *endpoints" "int num_endpoints" This function release resources needed for streams usage. Returns 0 on success or a LIBUSB_ERROR code on failure. .Pp .Ft void .Fn libusb_transfer_set_stream_id "struct libusb_transfer *transfer" "uint32_t stream_id" This function sets the stream ID for the given USB transfer. .Pp .Ft uint32_t .Fn libusb_transfer_get_stream_id "struct libusb_transfer *transfer" This function returns the stream ID for the given USB transfer. If no stream ID is used a value of zero is returned. .Sh USB EVENTS .Ft int .Fn libusb_try_lock_events "libusb_context *ctx" Try to acquire the event handling lock. Returns 0 if the lock was obtained and 1 if not. .Pp .Ft void .Fn libusb_lock_events "libusb_context *ctx" Acquire the event handling lock. This function is blocking. .Pp .Ft void .Fn libusb_unlock_events "libusb_context *ctx" Release the event handling lock. This will wake up any thread blocked on .Fn libusb_wait_for_event . .Pp .Ft int .Fn libusb_event_handling_ok "libusb_context *ctx" Determine if it still OK for this thread to be doing event handling. Returns 1 if event handling can start or continue. Returns 0 if this thread must give up the events lock. .Pp .Ft int .Fn libusb_event_handler_active "libusb_context *ctx" Determine if an active thread is handling events. Returns 1 if there is a thread handling events and 0 if there are no threads currently handling events. .Pp .Ft void .Fn libusb_interrupt_event_handler "libusb_context *ctx" Causes the .Fn libusb_handle_events familiy of functions to return to the caller one time. The .Fn libusb_handle_events functions may be called again after calling this function. .Pp .Ft void .Fn libusb_lock_event_waiters "libusb_context *ctx" Acquire the event_waiters lock. This lock is designed to be obtained in the situation where you want to be aware when events are completed, but some other thread is event handling so calling .Fn libusb_handle_events is not allowed. .Pp .Ft void .Fn libusb_unlock_event_waiters "libusb_context *ctx" Release the event_waiters lock. .Pp .Ft int .Fn libusb_wait_for_event "libusb_context *ctx" "struct timeval *tv" Wait for another thread to signal completion of an event. Must be called with the event waiters lock held, see .Fn libusb_lock_event_waiters . This will block until the timeout expires or a transfer completes or a thread releases the event handling lock through .Fn libusb_unlock_events . Returns 0 after a transfer completes or another thread stops event handling, and 1 if the timeout expired. .Pp .Ft int .Fn libusb_handle_events_timeout_completed "libusb_context *ctx" "struct timeval *tv" "int *completed" Handle any pending events by checking if timeouts have expired and by checking the set of file descriptors for activity. If the .Fa completed argument is not equal to NULL, this function will loop until a transfer completion callback sets the variable pointed to by the .Fa completed argument to non-zero. If the .Fa tv argument is not equal to NULL, this function will return LIBUSB_ERROR_TIMEOUT after the given timeout. Returns 0 on success, or a LIBUSB_ERROR code on failure or timeout. .Pp .Ft int .Fn libusb_handle_events_completed "libusb_context *ctx" "int *completed" Handle any pending events by checking the set of file descriptors for activity. If the .Fa completed argument is not equal to NULL, this function will loop until a transfer completion callback sets the variable pointed to by the .Fa completed argument to non-zero. Returns 0 on success, or a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_handle_events_timeout "libusb_context *ctx" "struct timeval *tv" Handle any pending events by checking if timeouts have expired and by checking the set of file descriptors for activity. Returns 0 on success, or a LIBUSB_ERROR code on failure or timeout. .Pp .Ft int .Fn libusb_handle_events "libusb_context *ctx" Handle any pending events in blocking mode with a sensible timeout. Returns 0 on success and a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_handle_events_locked "libusb_context *ctx" "struct timeval *tv" Handle any pending events by polling file descriptors, without checking if another thread is already doing so. Must be called with the event lock held. .Pp .Ft int .Fn libusb_get_next_timeout "libusb_context *ctx" "struct timeval *tv" Determine the next internal timeout that libusb needs to handle. Returns 0 if there are no pending timeouts, 1 if a timeout was returned, or a LIBUSB_ERROR code on failure or timeout. .Pp .Ft void .Fn libusb_set_pollfd_notifiers "libusb_context *ctx" "libusb_pollfd_added_cb added_cb" "libusb_pollfd_removed_cb remove_cb" "void *user_data" Register notification functions for file descriptor additions/removals. These functions will be invoked for every new or removed file descriptor that libusb uses as an event source. .Pp .Ft const struct libusb_pollfd ** .Fn libusb_get_pollfds "libusb_context *ctx" Retrieve a list of file descriptors that should be polled by your main loop as libusb event sources. Returns a NULL-terminated list on success or NULL on failure. .Pp .Ft int .Fn libusb_hotplug_register_callback "libusb_context *ctx" "libusb_hotplug_event events" "libusb_hotplug_flag flags" "int vendor_id" "int product_id" "int dev_class" "libusb_hotplug_callback_fn cb_fn" "void *user_data" "libusb_hotplug_callback_handle *handle" This function registers a hotplug filter. The .Fa events argument select which events makes the hotplug filter trigger. Available event values are LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED and LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT. One or more events must be specified. The .Fa vendor_id , .Fa product_id and .Fa dev_class arguments can be set to LIBUSB_HOTPLUG_MATCH_ANY to match any value in the USB device descriptor. Else the specified value is used for matching. If the .Fa flags argument is set to LIBUSB_HOTPLUG_ENUMERATE, all currently attached and matching USB devices will be passed to the hotplug filter, given by the .Fa cb_fn argument. Else the .Fa flags argument should be set to LIBUSB_HOTPLUG_NO_FLAGS. This function returns 0 upon success or a LIBUSB_ERROR code on failure. .Pp .Ft int .Fn libusb_hotplug_callback_fn "libusb_context *ctx" "libusb_device *device" "libusb_hotplug_event event" "void *user_data" The hotplug filter function. If this function returns non-zero, the filter is removed. Else the filter is kept and can receive more events. The .Fa user_data argument is the same as given when the filter was registered. The .Fa event argument can be either of LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED or LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT. .Pp .Ft void .Fn libusb_hotplug_deregister_callback "libusb_context *ctx" "libusb_hotplug_callback_handle handle" This function unregisters a hotplug filter. .Sh LIBUSB VERSION 0.1 COMPATIBILITY The library is also compliant with LibUSB version 0.1.12. .Pp .Fn usb_open .Fn usb_close .Fn usb_get_string .Fn usb_get_string_simple .Fn usb_get_descriptor_by_endpoint .Fn usb_get_descriptor .Fn usb_parse_descriptor .Fn usb_parse_configuration .Fn usb_destroy_configuration .Fn usb_fetch_and_parse_descriptors .Fn usb_bulk_write .Fn usb_bulk_read .Fn usb_interrupt_write .Fn usb_interrupt_read .Fn usb_control_msg .Fn usb_set_configuration .Fn usb_claim_interface .Fn usb_release_interface .Fn usb_set_altinterface .Fn usb_resetep .Fn usb_clear_halt .Fn usb_reset .Fn usb_strerror .Fn usb_init .Fn usb_set_debug .Fn usb_find_busses .Fn usb_find_devices .Fn usb_device .Fn usb_get_busses .Fn usb_check_connected .Fn usb_get_driver_np .Fn usb_detach_kernel_driver_np .Sh SEE ALSO .Xr libusb20 3 , .Xr usb 4 , .Xr usbconfig 8 , .Xr usbdump 8 .Pp .Lk https://libusb.info/ .Sh HISTORY .Nm support first appeared in .Fx 8.0 . diff --git a/libexec/rtld-elf/rtld.1 b/libexec/rtld-elf/rtld.1 index 31e046a5cdc4..5631c28e1f84 100644 --- a/libexec/rtld-elf/rtld.1 +++ b/libexec/rtld-elf/rtld.1 @@ -1,533 +1,533 @@ .\" Copyright (c) 1995 Paul Kranenburg .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgment: .\" This product includes software developed by Paul Kranenburg. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd July 24, 2025 +.Dd July 24, 2024 .Dt RTLD 1 .Os .Sh NAME .Nm ld-elf.so.1 , .Nm ld.so , .Nm rtld .Nd run-time link-editor .Sh DESCRIPTION The .Nm utility is a self-contained shared object providing run-time support for loading and link-editing shared objects into a process' address space. It is also commonly known as the dynamic linker. It uses the data structures contained within dynamically linked programs to determine which shared libraries are needed and loads them using the .Xr mmap 2 system call. .Pp After all shared libraries have been successfully loaded, .Nm proceeds to resolve external references from both the main program and all objects loaded. A mechanism is provided for initialization routines to be called on a per-object basis, giving a shared object an opportunity to perform any extra set-up before execution of the program proper begins. This is useful for C++ libraries that contain static constructors. .Pp When resolving dependencies for the loaded objects, .Nm translates dynamic token strings in rpath and soname. If the .Fl "z origin" option of the static linker was set when linking the binary, the token expansion is performed at the object load time, see .Xr ld 1 . The following strings are recognized now: .Bl -tag -width ".Pa $PLATFORM" .It Pa $ORIGIN Translated to the full path of the loaded object. .It Pa $OSNAME Translated to the name of the operating system implementation. .It Pa $OSREL Translated to the release level of the operating system. .It Pa $PLATFORM Translated to the machine hardware platform. .It Pa $LIB Translated to the system library path component on the platform. It is .Pa lib for native binaries, and typically .Pa lib32 for compat32 binaries. Other translations might exist for other ABIs supported on the platform. .El .Pp The .Nm utility itself is loaded by the kernel together with any dynamically-linked program that is to be executed. The kernel transfers control to the dynamic linker. After the dynamic linker has finished loading, relocating, and initializing the program and its required shared objects, it transfers control to the entry point of the program. The following search order is used to locate required shared objects: .Pp .Bl -enum -offset indent -compact .It .Dv DT_RPATH of the referencing object unless that object also contains a .Dv DT_RUNPATH tag .It .Dv DT_RPATH of the program unless the referencing object contains a .Dv DT_RUNPATH tag .It Path indicated by .Ev LD_LIBRARY_PATH environment variable .It .Dv DT_RUNPATH of the referencing object .It Hints file produced by the .Xr ldconfig 8 utility .It The .Pa /lib and .Pa /usr/lib directories, unless the referencing object was linked using the .Dq Fl z Ar nodefaultlib option .El .Pp The .Nm utility recognizes a number of environment variables that can be used to modify its behaviour. On 64-bit architectures, the linker for 32-bit objects recognizes all the environment variables listed below, but is being prefixed with .Ev LD_32_ , for example: .Ev LD_32_TRACE_LOADED_OBJECTS . If the activated image is setuid or setgid, the variables are ignored. .Bl -tag -width ".Ev LD_LIBMAP_DISABLE" .It Ev LD_DUMP_REL_POST If set, .Nm will print a table containing all relocations after symbol binding and relocation. .It Ev LD_DUMP_REL_PRE If set, .Nm will print a table containing all relocations before symbol binding and relocation. .It Ev LD_DYNAMIC_WEAK If set, use the ELF standard-compliant symbol lookup behavior: resolve to the first found symbol definition. .Pp By default, .Fx provides the non-standard symbol lookup behavior: when a weak symbol definition is found, remember the definition and keep searching in the remaining shared objects for a non-weak definition. If found, the non-weak definition is preferred, otherwise the remembered weak definition is returned. .Pp Symbols exported by dynamic linker itself (see .Xr dlfcn 3 ) are always resolved using .Fx rules regardless of the presence of the variable. This variable is unset for set-user-ID and set-group-ID programs. .It Ev LD_LIBMAP A library replacement list in the same format as .Xr libmap.conf 5 . For convenience, the characters .Ql = and .Ql \&, can be used instead of a space and a newline. This variable is parsed after .Xr libmap.conf 5 , and will override its entries. This variable is unset for set-user-ID and set-group-ID programs. .It Ev LD_LIBMAP_DISABLE If set, disables the use of .Xr libmap.conf 5 and .Ev LD_LIBMAP . This variable is unset for set-user-ID and set-group-ID programs. .It Ev LD_ELF_HINTS_PATH This variable will override the default location of .Dq hints file. This variable is unset for set-user-ID and set-group-ID programs. .It Ev LD_LIBRARY_PATH A colon separated list of directories, overriding the default search path for shared libraries. This variable is unset for set-user-ID and set-group-ID programs. .It Ev LD_LIBRARY_PATH_RPATH If the variable is specified and has a value starting with any of \'y\', \'Y\' or \'1\' symbols, the path specified by .Ev LD_LIBRARY_PATH variable is allowed to override the path from .Dv DT_RPATH for binaries which does not contain .Dv DT_RUNPATH tag. For such binaries, when the variable .Ev LD_LIBRARY_PATH_RPATH is set, .Dq Fl z Ar nodefaultlib link-time option is ignored as well. .It Ev LD_PRELOAD A list of shared libraries, separated by colons and/or white space, to be linked in before any other shared libraries. If the directory is not specified then the directories specified by .Ev LD_LIBRARY_PATH will be searched first followed by the set of built-in standard directories. This variable is unset for set-user-ID and set-group-ID programs. .It Ev LD_PRELOAD_FDS A colon separated list of file descriptor numbers for libraries. This is intended for preloading libraries in which we already have a file descriptor. This may optimize the process of loading libraries because we do not have to look for them in directories. It may also be useful in a capability base system where we do not have access to global namespaces such as the filesystem. .It Ev LD_LIBRARY_PATH_FDS A colon separated list of file descriptor numbers for library directories. This is intended for use within .Xr capsicum 4 sandboxes, when global namespaces such as the filesystem are unavailable. It is consulted just after LD_LIBRARY_PATH. This variable is unset for set-user-ID and set-group-ID programs. .It Ev LD_BIND_NOT When set to a nonempty string, prevents modifications of the PLT slots when doing bindings. As result, each call of the PLT-resolved function is resolved. In combination with debug output, this provides complete account of all bind actions at runtime. This variable is unset for set-user-ID and set-group-ID programs. .It Ev LD_BIND_NOW When set to a nonempty string, causes .Nm to relocate all external function calls before starting execution of the program. Normally, function calls are bound lazily, at the first call of each function. .Ev LD_BIND_NOW increases the start-up time of a program, but it avoids run-time surprises caused by unexpectedly undefined functions. .It Ev LD_TRACE_LOADED_OBJECTS When set to a nonempty string, causes .Nm to exit after loading the shared objects and printing a summary which includes the absolute pathnames of all objects, to standard output. .It Ev LD_TRACE_LOADED_OBJECTS_ALL When set to a nonempty string, causes .Nm to expand the summary to indicate which objects caused each object to be loaded. .It Ev LD_TRACE_LOADED_OBJECTS_FMT1 .It Ev LD_TRACE_LOADED_OBJECTS_FMT2 When set, these variables are interpreted as format strings a la .Xr printf 3 to customize the trace output and are used by .Xr ldd 1 Ns 's .Fl f option and allows .Xr ldd 1 to be operated as a filter more conveniently. If the dependency name starts with string .Pa lib , .Ev LD_TRACE_LOADED_OBJECTS_FMT1 is used, otherwise .Ev LD_TRACE_LOADED_OBJECTS_FMT2 is used. The following conversions can be used: .Bl -tag -width 4n .It Li %a The main program's name (also known as .Dq __progname ) . .It Li \&%A The value of the environment variable .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME . Typically used to print both the names of programs and shared libraries being inspected using .Xr ldd 1 . .It Li %o The library name. .It Li %p The full pathname as determined by .Nm rtld Ns 's library search rules. .It Li %x The library's load address. .El .Pp Additionally, .Ql \en and .Ql \et are recognized and have their usual meaning. .It Ev LD_UTRACE If set, .Nm will log events such as the loading and unloading of shared objects via .Xr utrace 2 . .It Ev LD_LOADFLTR If set, .Nm will process the filtee dependencies of the loaded objects immediately, instead of postponing it until required. Normally, the filtees are opened at the time of the first symbol resolution from the filter object. .It Ev LD_SHOW_AUXV If set, causes .Nm to dump content of the aux vector to standard output, before passing control to any user code. .It Ev LD_STATIC_TLS_EXTRA If the variable is specified and has a numeric value, .Nm will set the size of the static TLS extra space to the specified number of bytes. The static TLS extra space is used when loading objects compiled for initial-exec TLS code model with .Xr dlopen 3 . The minimum value that can be specified is \'128\'. .It Ev LD_NO_DL_ITERATE_PHDR_AFTER_FORK Allow .Xr dl_iterate_phdr 3 to block in callback, without causing deadlock with the .Xr fork 2 . The drawback is that the image started in this mode cannot use .Xr dl_iterate_phdr 3 after fork. .El .Sh DIRECT EXECUTION MODE .Nm is typically used implicitly, loaded by the kernel as requested by the .Dv PT_INTERP program header of the executed binary. .Fx also supports a direct execution mode for the dynamic linker. In this mode, the user explicitly executes .Nm and provides the path of the program to be linked and executed as an argument. This mode allows use of a non-standard dynamic linker for a program activation without changing the binary or without changing the installed dynamic linker. Execution options may be specified. .Pp The syntax of the direct invocation is .Bd -ragged -offset indent .Pa /libexec/ld-elf.so.1 .Op Fl b Ar exe .Op Fl d .Op Fl f Ar fd .Op Fl o Ar OPT=VALUE .Op Fl p .Op Fl u .Op Fl v .Op Fl - .Pa image_path .Op Ar image arguments .Ed .Pp The options are: .Bl -tag -width indent .It Fl b Ar exe Use the executable .Fa exe instead of .Fa image_path for activation. If this option is specified, .Ar image_path is only used to provide the .Va argv[0] value to the program. .It Fl d Turn off the emulation of the binary execute permission. .It Fl f Ar fd File descriptor .Ar fd references the binary to be activated by .Nm . It must already be opened in the process when executing .Nm . If this option is specified, .Ar image_path is only used to provide the .Va argv[0] value to the program. .It Fl o Ar OPT=VALUE Set the .Ar OPT configuration variable to the value .Ar VALUE . The possible variable names are listed above as .Ev LD_ prefixed environment variables, but here are referenced without the .Ev LD_ prefix. A configuration variable set this way does not leak into the activated image's environment. .Pp The option can be repeated as many times as needed to set all configuration parameters. The parameters set using this option have priority over the same parameters assigned via environment. .It Fl p If the .Pa image_path argument specifies a name which does not contain a slash .Dq Li / character, .Nm uses the search path provided by the environment variable .Dv PATH to find the binary to execute. .It Fl u Ignore all .Ev LD_ environment variables and previous command line .Fl o options that otherwise affect the dynamic linker behavior. .It Fl v Display information about this run-time linker binary, then exit. .It Fl - Ends the .Nm options. The argument following .Fl - is interpreted as the path of the binary to execute. .El .Pp In the direct execution mode, .Nm emulates verification of the binary execute permission for the current user. This is done to avoid breaking user expectations in naively restricted execution environments. The verification only uses Unix .Dv DACs , ignores .Dv ACLs , and is naturally prone to race conditions. Environments which rely on such restrictions are weak and breakable on their own. It can be turned off with the .Fl d option. .Sh VERSIONING Newer .Nm might provide some features or changes in runtime behavior that cannot be easily detected at runtime by checking of the normal exported symbols. Note that it is almost always wrong to verify .Dv __FreeBSD_version in userspace to detect features, either at compile or at run time, because either kernel, or libc, or environment variables could not match the running .Nm . .Pp To solve the problem, .Nm exports some feature indicators in the .Fx private symbols namespace .Dv FBSDprivate_1.0 . Symbols start with the .Dv _rtld_version prefix. Current list of defined symbols and corresponding features is: .Bl -tag -width indent .It Dv _rtld_version__FreeBSD_version Symbol exports the value of the .Dv __FreeBSD_version definition as it was provided during the .Nm build. The symbol is always present since the .Dv _rtld_version facility was introduced. .It Dv _rtld_version_laddr_offset The .Va l_addr member of the .Vt link_map structure contains the load offset of the shared object. Before that, .Va l_addr contained the base address of the library. See .Xr dlinfo 3 . .Pp Also it indicates the presence of .Va l_refname member of the structure. .It Dv _rtld_version_dlpi_tls_data The .Va dlpi_tls_data member of the structure .Vt dl_phdr_info contains the address of the module TLS segment for the calling thread, and not the address of the initialization segment. .El .Sh FILES .Bl -tag -width ".Pa /var/run/ld-elf32.so.hints" -compact .It Pa /var/run/ld-elf.so.hints Hints file. .It Pa /var/run/ld-elf32.so.hints Hints file for 32-bit binaries on 64-bit system. .It Pa /etc/libmap.conf The libmap configuration file. .It Pa /etc/libmap32.conf The libmap configuration file for 32-bit binaries on 64-bit system. .El .Sh SEE ALSO .Xr ld 1 , .Xr ldd 1 , .Xr dlinfo 3 , .Xr capsicum 4 , .Xr elf 5 , .Xr libmap.conf 5 , .Xr ldconfig 8 diff --git a/share/man/man4/enic.4 b/share/man/man4/enic.4 index 257a95fa9d32..1783b05dfa12 100644 --- a/share/man/man4/enic.4 +++ b/share/man/man4/enic.4 @@ -1,88 +1,88 @@ .\" Copyright 2008-2017 Cisco Systems, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS `AS IS' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd Sept 7, 2022 +.Dd September 7, 2022 .Dt ENIC 4 .Os .Sh NAME .Nm enic .Nd "VIC Ethernet NIC driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device iflib" .Cd "device enic" .Ed .Pp To load the driver as a module at run-time, run the following command as root: .Bd -literal -offset indent kldload if_enic .Ed .Pp To load the driver as a module at boot time, place the following lines in .Xr loader.conf 5 : .Bd -literal -offset indent if_enic_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for Cisco Virtual Interface Card. Support is limited to basic network connectivity. Media is controlled by the NIC itself since there can be multiple virtual PCI NIC devices exposed to the PCI bus. .Sh HARDWARE The .Nm driver should supports all known Cisco VIC cards. .Sh CONFIGURATION The .Nm network interface is configured using .Xr ifconfig 8 and the .Xr sysctl 8 tree at .Dv dev.enic. . All configurable entries are also tunables, and can be put directly into the .Xr loader.conf 5 for persistent configuration. .Sh SEE ALSO .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 14.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Cisco UCS team based of the DPDK driver. diff --git a/usr.sbin/gssd/gssd.8 b/usr.sbin/gssd/gssd.8 index 4240bf28867d..8c330a134a6f 100644 --- a/usr.sbin/gssd/gssd.8 +++ b/usr.sbin/gssd/gssd.8 @@ -1,112 +1,112 @@ .\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/ .\" Authors: Doug Rabson .\" Developed with Red Inc: Alfred Perlstein .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd April 10 2020 +.Dd April 10, 2020 .Dt GSSD 8 .Os .Sh NAME .Nm gssd .Nd "Generic Security Services Daemon" .Sh SYNOPSIS .Nm .Op Fl d .Op Fl h .Op Fl v .Op Fl s Ar dir-list .Op Fl c Ar file-substring .Op Fl r Ar preferred-realm .Sh DESCRIPTION The .Nm program provides support for the kernel GSS-API implementation. .Pp The options are as follows: .Bl -tag -width indent .It Fl d Run in debug mode. In this mode, .Nm will not fork when it starts. .It Fl h Enable support for host-based initiator credentials. This permits a kerberized NFS mount to use a service principal in the default Kerberos 5 keytab file for access. Such access is enabled via the gssname option for the .Xr mount_nfs 8 command. .It Fl v Run in verbose mode. In this mode, .Nm will log activity messages to syslog using LOG_INFO | LOG_DAEMON or to stderr, if the .Fl d option has also been specified. The minor status is logged as a decimal number, since it is actually a Kerberos return status, which is signed. .It Fl s Ar dir-list Look for an appropriate credential cache file in this list of directories. The list should be full pathnames from root, separated by ':' characters. Usually this list will simply be "/tmp". Without this option, .Nm assumes that the credential cache file is called /tmp/krb5cc_, where is the effective uid for the RPC caller. .It Fl c Ar file-substring Set a file-substring for the credential cache file names. Only files with this substring embedded in their names will be selected as candidates when .Fl s has been specified. If not specified, it defaults to "krb5cc_". .It Fl r Ar preferred-realm Use Kerberos credentials for this realm when searching for credentials in directories specified with .Fl s . If not specified, the default Kerberos realm will be used. .El .Sh FILES .Bl -tag -width ".Pa /etc/krb5.keytab" -compact .It Pa /etc/krb5.keytab Contains Kerberos service principals which may be used as credentials by kernel GSS-API services. .El .Sh EXIT STATUS .Ex -std .Sh SEE ALSO .Xr gssapi 3 , .Xr syslog 3 , .Xr mount_nfs 8 .Sh HISTORY The .Nm manual page first appeared in .Fx 8.0 . .Sh AUTHORS This manual page was written by .An Doug Rabson Aq Mt dfr@FreeBSD.org .