diff options
Diffstat (limited to 'share/man/man9')
85 files changed, 3316 insertions, 1251 deletions
diff --git a/share/man/man9/BUS_CHILD_DETACHED.9 b/share/man/man9/BUS_CHILD_DETACHED.9 index 4cc00a49465b..8b59d1362d3d 100644 --- a/share/man/man9/BUS_CHILD_DETACHED.9 +++ b/share/man/man9/BUS_CHILD_DETACHED.9 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 21, 2012 +.Dd January 9, 2025 .Dt BUS_CHILD_DETACHED 9 .Os .Sh NAME @@ -39,7 +39,10 @@ .Sh DESCRIPTION The .Fn BUS_CHILD_DETACHED -method is invoked by the new-bus framework after a device is detached. +method is invoked by the new-bus framework after a device is detached +or if a driver's attach routine +.Pq see Xr DEVICE_ATTACH 9 +fails. A bus driver can provide an implementation of this method to reclaim any resources allocated on behalf of the child or to cleanup state not properly released by a diff --git a/share/man/man9/BUS_CONFIG_INTR.9 b/share/man/man9/BUS_CONFIG_INTR.9 index cf6ecbb4b823..aaeb6c3ec089 100644 --- a/share/man/man9/BUS_CONFIG_INTR.9 +++ b/share/man/man9/BUS_CONFIG_INTR.9 @@ -23,12 +23,13 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd January 15, 2017 +.Dd January 16, 2025 .Dt BUS_CONFIG_INTR 9 .Os .\" .Sh NAME -.Nm BUS_CONFIG_INTR +.Nm BUS_CONFIG_INTR , +.Nm bus_config_intr .Nd "configure interrupt polarity and trigger mode" .\" .Sh SYNOPSIS @@ -36,9 +37,13 @@ .In sys/bus.h .Ft int .Fo BUS_CONFIG_INTR +.Fa "device_t bus" "device_t dev" "int irq" "enum intr_trigger trig" +.Fa "enum intr_polarity pol" +.Fc +.Ft int +.Fo bus_config_intr .Fa "device_t dev" "int irq" "enum intr_trigger trig" "enum intr_polarity pol" .Fc -.\" .Sh DESCRIPTION The .Fn BUS_CONFIG_INTR @@ -53,6 +58,11 @@ that it is called prior to .Xr BUS_SETUP_INTR 9 . .Pp The +.Fn bus_config_intr +function is a simple wrapper around +.Fn BUS_CONFIG_INTR . +.Pp +The .Fa trig argument can be one of: .Bl -tag -width ".Dv INTR_TRIGGER_CONFORM" diff --git a/share/man/man9/BUS_HINTED_CHILD.9 b/share/man/man9/BUS_HINTED_CHILD.9 new file mode 100644 index 000000000000..860ee3a995e3 --- /dev/null +++ b/share/man/man9/BUS_HINTED_CHILD.9 @@ -0,0 +1,37 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 John Baldwin <jhb@FreeBSD.org> +.Dd February 5, 2025 +.Dt BUS_HINTED_CHILD 9 +.Os +.Sh NAME +.Nm BUS_HINTED_CHILD +.Nd notify a bus device about a potential child device identified by hints +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn BUS_HINTED_CHILD "device_t dev" "const char *dname" "int dunit" +.Sh DESCRIPTION +The +.Fn BUS_HINTED_CHILD +method is invoked by the +.Xr bus_enumerate_hinted_children 9 +function for each set of named hints whose +.Dq at +hint matches the bus device +.Fa dev . +Typically, this method should determine if the set of hints for the given +device name and unit sufficiently describe a new device. +If so, a new device should be added via +.Xr BUS_ADD_CHILD 9 . +.Sh SEE ALSO +.Xr BUS_ADD_CHILD 9 , +.Xr bus_enumerate_hinted_children 9 , +.Xr device 9 +.Sh HISTORY +The +.Fn BUS_HINTED_CHILD +method first appeared in +.Fx 6.2 . diff --git a/share/man/man9/DEVICE_ATTACH.9 b/share/man/man9/DEVICE_ATTACH.9 index 0946e1f13b7c..8e7c46252a6f 100644 --- a/share/man/man9/DEVICE_ATTACH.9 +++ b/share/man/man9/DEVICE_ATTACH.9 @@ -26,7 +26,7 @@ .\" (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 15, 2017 +.Dd February 5, 2025 .Dt DEVICE_ATTACH 9 .Os .Sh NAME @@ -46,19 +46,20 @@ The .Fn DEVICE_ATTACH method should initialize the hardware and allocate other system resources (such as -.Xr devfs 5 +.Xr devfs 4 entries). .Pp Devices which implement buses should use this method to probe for the existence of devices attached to the bus and add them as children. If this is combined with the use of -.Xr bus_generic_attach 9 +.Xr bus_attach_children 9 the child devices will be automatically probed and attached. .Sh RETURN VALUES Zero is returned on success, otherwise an appropriate error is returned. .Sh SEE ALSO -.Xr devfs 5 , +.Xr devfs 4 , +.Xr bus_attach_children 9 , .Xr device 9 , .Xr DEVICE_DETACH 9 , .Xr DEVICE_IDENTIFY 9 , diff --git a/share/man/man9/DEVICE_IDENTIFY.9 b/share/man/man9/DEVICE_IDENTIFY.9 index 4892e66eb214..31063ae60dff 100644 --- a/share/man/man9/DEVICE_IDENTIFY.9 +++ b/share/man/man9/DEVICE_IDENTIFY.9 @@ -26,44 +26,46 @@ .\" (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 15, 2017 +.Dd February 5, 2025 .Dt DEVICE_IDENTIFY 9 .Os .Sh NAME .Nm DEVICE_IDENTIFY -.Nd identify a device, register it +.Nd identify new child devices and register them .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft void .Fn DEVICE_IDENTIFY "driver_t *driver" "device_t parent" .Sh DESCRIPTION -The identify function for a device is only needed for devices on buses -that cannot identify their children independently, e.g.\& the ISA bus. -It is used to recognize the device (usually done by accessing non-ambiguous -registers in the hardware) and to tell the kernel about it and thus -creating a new device instance. +The identify method of a device driver is used to add devices that cannot be +enumerated by the standard method on a bus device. +Devices can be enumerated in various ways including accessing non-ambiguous +device registers and parsing firmware tables. +Software-only pseudo devices are also often enumerated via identify methods. .Pp +For each newly identified device, +a new device instance should be created by invoking the .Xr BUS_ADD_CHILD 9 -is used to register the device as a child of the bus. -The device's resources (such as IRQ and I/O ports) are registered -with the kernel by calling -.Fn bus_set_resource -for each resource (refer to +method. +If the identify method is able to discover other properties about the new +device, those should also be set. +For example, device resources should be added to the device by calling .Xr bus_set_resource 9 -for more information). +for each resource. .Pp -Since the device tree and the device driver tree are disjoint, the -.Fn DEVICE_IDENTIFY -routine needs to take this into account. -If you load and unload your device driver that has the identify -routine, the child node has the potential for adding the same node -multiple times unless specific measure are taken to preclude that -possibility. +An identify method might be invoked multiple times. +If a device driver is unloaded and loaded, +the identify method will be called a second time after being reloaded. +As a result, the identify method should avoid duplicate devices. +Devices added by identify methods typically use a fixed device name +in which case +.Xr device_find_child 9 +can be used to detect existing devices. .Sh EXAMPLES The following pseudo-code shows an example of a function that probes for a piece of hardware and registers it and its resource -(an I/O port) with the kernel. +(an I/O port) with the parent bus device. .Bd -literal void foo_identify(driver_t *driver, device_t parent) @@ -72,21 +74,18 @@ foo_identify(driver_t *driver, device_t parent) retrieve_device_information; if (devices matches one of your supported devices && - not already in device tree) { - child = BUS_ADD_CHILD(parent, 0, "foo", -1); + device_get_child(parent, "foo", DEVICE_UNIT_ANY) == NULL) { + child = BUS_ADD_CHILD(parent, 0, "foo", DEVICE_UNIT_ANY); bus_set_resource(child, SYS_RES_IOPORT, 0, FOO_IOADDR, 1); } } .Ed .Sh SEE ALSO .Xr BUS_ADD_CHILD 9 , +.Xr bus_identify_children 9 , .Xr bus_set_resource 9 , .Xr device 9 , -.Xr device_add_child 9 , -.Xr DEVICE_ATTACH 9 , -.Xr DEVICE_DETACH 9 , -.Xr DEVICE_PROBE 9 , -.Xr DEVICE_SHUTDOWN 9 +.Xr device_find_child 9 .Sh AUTHORS This manual page was written by .An Alexander Langer Aq Mt alex@FreeBSD.org . diff --git a/share/man/man9/MD5.9 b/share/man/man9/MD5.9 deleted file mode 100644 index 4418cc40b976..000000000000 --- a/share/man/man9/MD5.9 +++ /dev/null @@ -1,76 +0,0 @@ -.\" $OpenBSD: md5.9,v 1.1 1996/04/17 21:40:14 mickey Exp $ -.\" -.\" Copyright (c) 1996 Michael Shalayeff -.\" 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 acknowledgement: -.\" This product includes software developed by Michael Shalayeff -.\" 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 April 17, 1996 -.Dt MD5 9 -.Os -.Sh NAME -.Nm MD5 , -.Nm MD5Init , -.Nm MD5Transform -.Nd message digest routines -.Sh SYNOPSIS -.In sys/types.h -.In sys/md5.h -.Ft void -.Fn MD5Init "MD5_CTX *buf" -.Ft void -.Fn MD5Transform "uint32_t buf[4]" "const unsigned char block[64]" -.Sh DESCRIPTION -The -.Nm -module implements the RSA Data Security, Inc.\& MD5 Message-Digest Algorithm -(MD5). -It produces 128-bit MD5 Digest of data. -.Bl -hang -width MD5Transformxxx -.It Pa MD5Init -must be called just before -.Fn MD5Transform -will be used to produce a digest. -The -.Fa buf -argument is the storage for the digest being produced on subsequent -calls to the -.Fn MD5Transform -routine. -.It Pa MD5Transform -is the core of the MD5 algorithm, this alters an existing MD5 hash -kept in -.Fa buf -to reflect the addition of 64 characters -of new data passed in -.Fa block -argument. -.El -.Sh COPYRIGHTS -The code for MD5 transform was taken from Colin Plumb's -implementation, which has been placed in the public domain. -The MD5 cryptographic checksum was devised by Ronald Rivest, and is -documented in RFC 1321, "The MD5 Message Digest Algorithm". diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index dfc9bd996504..5bcde3030ebc 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,6 +1,7 @@ - .include <src.opts.mk> +PACKAGE= kernel + MAN= accept_filter.9 \ accf_data.9 \ accf_dns.9 \ @@ -29,6 +30,7 @@ MAN= accept_filter.9 \ BUS_ADD_CHILD.9 \ bus_adjust_resource.9 \ bus_alloc_resource.9 \ + bus_attach_children.9 \ BUS_BIND_INTR.9 \ bus_child_present.9 \ BUS_CHILD_DELETED.9 \ @@ -36,10 +38,8 @@ MAN= accept_filter.9 \ BUS_CHILD_LOCATION.9 \ BUS_CHILD_PNPINFO.9 \ BUS_CONFIG_INTR.9 \ - bus_delayed_attach_children.9 \ BUS_DESCRIBE_INTR.9 \ bus_dma.9 \ - bus_generic_attach.9 \ bus_generic_detach.9 \ bus_generic_new_pass.9 \ bus_generic_print_child.9 \ @@ -48,6 +48,7 @@ MAN= accept_filter.9 \ BUS_GET_CPUS.9 \ BUS_GET_PROPERTY.9 \ bus_get_resource.9 \ + BUS_HINTED_CHILD.9 \ bus_map_resource.9 \ BUS_NEW_PASS.9 \ BUS_PRINT_CHILD.9 \ @@ -62,12 +63,15 @@ MAN= accept_filter.9 \ callout.9 \ casuword.9 \ cd.9 \ + cdefs.9 \ cnv.9 \ condvar.9 \ config_intrhook.9 \ contigmalloc.9 \ copy.9 \ + coredumper_register.9 \ counter.9 \ + cpu_machdep.9 \ cpuset.9 \ cr_bsd_visible.9 \ cr_cansee.9 \ @@ -218,7 +222,6 @@ MAN= accept_filter.9 \ mbchain.9 \ mbuf.9 \ mbuf_tags.9 \ - MD5.9 \ mdchain.9 \ memcchr.9 \ memguard.9 \ @@ -393,7 +396,6 @@ MAN= accept_filter.9 \ vm_map_max.9 \ vm_map_protect.9 \ vm_map_remove.9 \ - vm_map_simplify_entry.9 \ vm_map_stack.9 \ vm_map_submap.9 \ vm_map_sync.9 \ @@ -435,6 +437,7 @@ MAN= accept_filter.9 \ VOP_GETEXTATTR.9 \ VOP_GETPAGES.9 \ VOP_INACTIVE.9 \ + VOP_INOTIFY.9 \ VOP_IOCTL.9 \ VOP_LINK.9 \ VOP_LISTEXTATTR.9 \ @@ -672,7 +675,12 @@ MLINKS+=buf_ring.9 buf_ring_alloc.9 \ buf_ring.9 buf_ring_peek.9 MLINKS+=bus_activate_resource.9 bus_deactivate_resource.9 MLINKS+=bus_alloc_resource.9 bus_alloc_resource_any.9 +MLINKS+=bus_attach_children.9 bus_delayed_attach_children.9 \ + bus_attach_children.9 bus_detach_children.9 \ + bus_attach_children.9 bus_enumerate_hinted_children.9 \ + bus_attach_children.9 bus_identify_children.9 MLINKS+=BUS_BIND_INTR.9 bus_bind_intr.9 +MLINKS+=BUS_CONFIG_INTR.9 bus_config_intr.9 MLINKS+=BUS_DESCRIBE_INTR.9 bus_describe_intr.9 MLINKS+=bus_dma.9 busdma.9 \ bus_dma.9 bus_dmamap_create.9 \ @@ -691,6 +699,9 @@ MLINKS+=bus_dma.9 busdma.9 \ bus_dma.9 bus_dmamem_free.9 \ bus_dma.9 bus_dma_tag_create.9 \ bus_dma.9 bus_dma_tag_destroy.9 +MLINKS+=bus_generic_print_child.9 bus_print_child_domain.9 \ + bus_generic_print_child.9 bus_print_child_footer.9 \ + bus_generic_print_child.9 bus_print_child_header.9 MLINKS+=bus_generic_read_ivar.9 bus_generic_write_ivar.9 MLINKS+=BUS_GET_CPUS.9 bus_get_cpus.9 MLINKS+=bus_map_resource.9 bus_unmap_resource.9 \ @@ -885,8 +896,7 @@ MLINKS+=config_intrhook.9 config_intrhook_disestablish.9 \ config_intrhook.9 config_intrhook_drain.9 \ config_intrhook.9 config_intrhook_establish.9 \ config_intrhook.9 config_intrhook_oneshot.9 -MLINKS+=contigmalloc.9 contigmalloc_domainset.9 \ - contigmalloc.9 contigfree.9 +MLINKS+=contigmalloc.9 contigmalloc_domainset.9 MLINKS+=casuword.9 casueword.9 \ casuword.9 casueword32.9 \ casuword.9 casuword32.9 @@ -896,6 +906,7 @@ MLINKS+=copy.9 copyin.9 \ copy.9 copyout.9 \ copy.9 copyout_nofault.9 \ copy.9 copystr.9 +MLINKS+=coredumper_register.9 coredumper_unregister.9 MLINKS+=counter.9 counter_u64_alloc.9 \ counter.9 counter_u64_free.9 \ counter.9 counter_u64_add.9 \ @@ -909,6 +920,27 @@ MLINKS+=counter.9 counter_u64_alloc.9 \ counter.9 SYSCTL_ADD_COUNTER_U64.9 \ counter.9 SYSCTL_COUNTER_U64_ARRAY.9 \ counter.9 SYSCTL_ADD_COUNTER_U64_ARRAY.9 +MLINKS+=cpu_machdep.9 cpu_copy_thread.9 \ + cpu_machdep.9 cpu_exec_vmspace_reuse.9 \ + cpu_machdep.9 cpu_exit.9 \ + cpu_machdep.9 cpu_fetch_syscall_args.9 \ + cpu_machdep.9 cpu_fork.9 \ + cpu_machdep.9 cpu_fork_kthread_handler.9 \ + cpu_machdep.9 cpu_idle.9 \ + cpu_machdep.9 cpu_idle_wakeup.9 \ + cpu_machdep.9 cpu_procctl.9 \ + cpu_machdep.9 cpu_ptrace.9 \ + cpu_machdep.9 cpu_set_syscall_retval.9 \ + cpu_machdep.9 cpu_set_upcall.9 \ + cpu_machdep.9 cpu_set_user_tls.9 \ + cpu_machdep.9 cpu_switch.9 \ + cpu_machdep.9 cpu_sync_core.9 \ + cpu_machdep.9 cpu_thread_alloc.9 \ + cpu_machdep.9 cpu_thread_clean.9 \ + cpu_machdep.9 cpu_thread_exit.9 \ + cpu_machdep.9 cpu_thread_free.9 \ + cpu_machdep.9 cpu_throw.9 \ + cpu_machdep.9 cpu_update_pcb.9 MLINKS+=cpuset.9 CPUSET_T_INITIALIZER.9 \ cpuset.9 CPUSET_FSET.9 \ cpuset.9 CPU_CLR.9 \ @@ -1020,6 +1052,9 @@ MLINKS+=device_set_desc.9 device_get_desc.9 \ device_set_desc.9 device_set_descf.9 \ device_set_desc.9 device_set_desc_copy.9 MLINKS+=device_set_flags.9 device_get_flags.9 +MLINKS+=device_probe_and_attach.9 device_attach.9 \ + device_probe_and_attach.9 device_detach.9 \ + device_probe_and_attach.9 device_probe.9 MLINKS+=devstat.9 devicestat.9 \ devstat.9 devstat_new_entry.9 \ devstat.9 devstat_end_transaction.9 \ @@ -1336,13 +1371,15 @@ MLINKS+=ifnet.9 if_addmulti.9 \ ifnet.9 ifa_ifwithnet.9 \ ifnet.9 ifa_ref.9 \ ifnet.9 ifaddr.9 \ - ifnet.9 ifaddr_byindex.9 \ ifnet.9 ifaof_ifpforaddr.9 \ ifnet.9 ifioctl.9 \ ifnet.9 ifpromisc.9 \ ifnet.9 ifqueue.9 \ ifnet.9 ifunit.9 \ ifnet.9 ifunit_ref.9 +# IfAPI +MLINKS+=ifnet.9 ifapi.9 + MLINKS+=insmntque.9 insmntque1.9 MLINKS+=intr_event.9 intr_event_add_handler.9 \ intr_event.9 intr_event_create.9 \ @@ -1431,9 +1468,14 @@ MLINKS+=lock.9 lockdestroy.9 \ lock.9 lockmgr_args_rw.9 \ lock.9 lockmgr_assert.9 \ lock.9 lockmgr_disown.9 \ + lock.9 lockmgr_disowned.9 \ + lock.9 lockmgr_lock_flags.9 \ lock.9 lockmgr_printinfo.9 \ lock.9 lockmgr_recursed.9 \ lock.9 lockmgr_rw.9 \ + lock.9 lockmgr_slock.9 \ + lock.9 lockmgr_unlock.9 \ + lock.9 lockmgr_xlock.9 \ lock.9 lockstatus.9 MLINKS+=LOCK_PROFILING.9 MUTEX_PROFILING.9 MLINKS+=make_dev.9 destroy_dev.9 \ @@ -1542,8 +1584,6 @@ MLINKS+=\ mbuf_tags.9 m_tag_next.9 \ mbuf_tags.9 m_tag_prepend.9 \ mbuf_tags.9 m_tag_unlink.9 -MLINKS+=MD5.9 MD5Init.9 \ - MD5.9 MD5Transform.9 MLINKS+=mdchain.9 md_append_record.9 \ mdchain.9 md_done.9 \ mdchain.9 md_get_int64.9 \ @@ -1573,8 +1613,6 @@ MLINKS+=microuptime.9 binuptime.9 \ microuptime.9 getsbinuptime.9 \ microuptime.9 nanouptime.9 \ microuptime.9 sbinuptime.9 -MLINKS+=mi_switch.9 cpu_switch.9 \ - mi_switch.9 cpu_throw.9 MLINKS+=mod_cc.9 CCV.9 \ mod_cc.9 DECLARE_CC_MODULE.9 MLINKS+=mtx_pool.9 mtx_pool_alloc.9 \ @@ -1605,7 +1643,8 @@ MLINKS+=mutex.9 mtx_assert.9 \ mutex.9 mtx_unlock_flags.9 \ mutex.9 mtx_unlock_spin.9 \ mutex.9 mtx_unlock_spin_flags.9 -MLINKS+=namei.9 NDFREE.9 \ +MLINKS+=namei.9 NDFREE_PNBUF.9 \ + namei.9 NDINIT_AT.9 \ namei.9 NDINIT.9 MLINKS+=netisr.9 netisr_clearqdrops.9 \ netisr.9 netisr_default_flow2cpu.9 \ @@ -1756,10 +1795,12 @@ MLINKS+=panic.9 vpanic.9 \ panic.9 KERNEL_PANICKED.9 MLINKS+=pci.9 pci_alloc_msi.9 \ pci.9 pci_alloc_msix.9 \ + pci.9 pci_clear_pme.9 \ pci.9 pci_disable_busmaster.9 \ pci.9 pci_disable_io.9 \ pci.9 pci_enable_busmaster.9 \ pci.9 pci_enable_io.9 \ + pci.9 pci_enable_pme.9 \ pci.9 pci_find_bsf.9 \ pci.9 pci_find_cap.9 \ pci.9 pci_find_dbsf.9 \ @@ -1772,6 +1813,7 @@ MLINKS+=pci.9 pci_alloc_msi.9 \ pci.9 pci_get_powerstate.9 \ pci.9 pci_get_vpd_ident.9 \ pci.9 pci_get_vpd_readonly.9 \ + pci.9 pci_has_pm.9 \ pci.9 pci_iov_attach.9 \ pci.9 pci_iov_attach_name.9 \ pci.9 pci_iov_detach.9 \ @@ -2244,6 +2286,7 @@ MLINKS+=taskqueue.9 TASK_INIT.9 \ taskqueue.9 taskqueue_drain_timeout.9 \ taskqueue.9 taskqueue_enqueue.9 \ taskqueue.9 taskqueue_enqueue_timeout.9 \ + taskqueue.9 taskqueue_enqueue_timeout_sbt.9 \ taskqueue.9 TASKQUEUE_FAST_DEFINE.9 \ taskqueue.9 TASKQUEUE_FAST_DEFINE_THREAD.9 \ taskqueue.9 taskqueue_free.9 \ @@ -2378,8 +2421,6 @@ MLINKS+=vm_page_alloc.9 vm_page_alloc_after.9 \ vm_page_alloc.9 vm_page_alloc_contig_domain.9 \ vm_page_alloc.9 vm_page_alloc_domain.9 \ vm_page_alloc.9 vm_page_alloc_domain_after.9 \ - vm_page_alloc.9 vm_page_alloc_freelist.9 \ - vm_page_alloc.9 vm_page_alloc_freelist_domain.9 \ vm_page_alloc.9 vm_page_alloc_noobj.9 \ vm_page_alloc.9 vm_page_alloc_noobj_contig.9 \ vm_page_alloc.9 vm_page_alloc_noobj_contig_domain.9 \ @@ -2424,6 +2465,7 @@ MLINKS+=VOP_CREATE.9 VOP_MKDIR.9 \ MLINKS+=VOP_FSYNC.9 VOP_FDATASYNC.9 MLINKS+=VOP_GETPAGES.9 VOP_PUTPAGES.9 MLINKS+=VOP_INACTIVE.9 VOP_RECLAIM.9 +MLINKS+=VOP_INOTIFY.9 VOP_INOTIFY_ADD_WATCH.9 MLINKS+=VOP_LOCK.9 vn_lock.9 \ VOP_LOCK.9 VOP_ISLOCKED.9 \ VOP_LOCK.9 VOP_UNLOCK.9 diff --git a/share/man/man9/OF_device_from_xref.9 b/share/man/man9/OF_device_from_xref.9 index 85a19df6641b..0b858866b654 100644 --- a/share/man/man9/OF_device_from_xref.9 +++ b/share/man/man9/OF_device_from_xref.9 @@ -23,19 +23,22 @@ .\" (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 9, 2018 +.Dd April 3, 2025 .Dt OF_DEVICE_FROM_XREF 9 .Os .Sh NAME .Nm OF_device_from_xref , .Nm OF_xref_from_device , .Nm OF_device_register_xref +.Nm OF_device_unregister_xref .Nd "manage mappings between xrefs and devices" .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft int .Fn OF_device_register_xref "phandle_t xref" "device_t dev" +.Ft void +.Fn OF_device_unregister_xref "phandle_t xref" "device_t dev" .Ft device_t .Fn OF_device_from_xref "phandle_t xref" .Ft phandle_t @@ -57,6 +60,15 @@ If a mapping entry for already exists, it is replaced with the new one. The function always returns 0. .Pp +.Fn OF_device_unregister_xref +removes a map entry from the effective phandle +.Fa xref +to device +.Fa dev . +If a mapping entry for +.Fa xref +does not exists, it silently returns. +.Pp .Fn OF_device_from_xref returns a device_t instance associated with the effective phandle .Fa xref . diff --git a/share/man/man9/OF_node_from_xref.9 b/share/man/man9/OF_node_from_xref.9 index bd5e2bcab68f..755c82951382 100644 --- a/share/man/man9/OF_node_from_xref.9 +++ b/share/man/man9/OF_node_from_xref.9 @@ -1,4 +1,6 @@ .\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" .\" Copyright (c) 2018 Oleksandr Tymoshenko <gonzo@FreeBSD.org> .\" .\" All rights reserved. @@ -70,9 +72,9 @@ If one cannot be found or the OpenFirmware implementation does not support effective phandles, the function returns the input value. .Pp -.Fn OF_xref_from_xref +.Fn OF_xref_from_node returns the effective phandle for the kernel phandle -.Fa xref . +.Fa node . If one cannot be found or the OpenFirmware implementation does not support effective phandles, the function returns the input value. diff --git a/share/man/man9/PCI_IOV_ADD_VF.9 b/share/man/man9/PCI_IOV_ADD_VF.9 index d13cb6e1ddc9..512b0b8668cc 100644 --- a/share/man/man9/PCI_IOV_ADD_VF.9 +++ b/share/man/man9/PCI_IOV_ADD_VF.9 @@ -31,7 +31,7 @@ .Nd inform a PF driver that a VF is being created .Sh SYNOPSIS .In sys/bus.h -.In machine/stdarg.h +.In sys/stdarg.h .In sys/nv.h .In dev/pci/pci_iov.h .Ft int diff --git a/share/man/man9/PCI_IOV_INIT.9 b/share/man/man9/PCI_IOV_INIT.9 index 66b1e693cedb..8ce94800f6d1 100644 --- a/share/man/man9/PCI_IOV_INIT.9 +++ b/share/man/man9/PCI_IOV_INIT.9 @@ -31,7 +31,7 @@ .Nd enable SR-IOV on a PF device .Sh SYNOPSIS .In sys/bus.h -.In machine/stdarg.h +.In sys/stdarg.h .In sys/nv.h .In dev/pci/pci_iov.h .Ft int diff --git a/share/man/man9/VOP_ADVISE.9 b/share/man/man9/VOP_ADVISE.9 index 3decc0c2eac8..c6e8791615ce 100644 --- a/share/man/man9/VOP_ADVISE.9 +++ b/share/man/man9/VOP_ADVISE.9 @@ -39,7 +39,7 @@ .Sh DESCRIPTION This call applies advice for a range of a file's data. It is used to implement the -.Xr posix_fadvise +.Xr posix_fadvise 2 system call. .Pp Its arguments are: diff --git a/share/man/man9/VOP_ALLOCATE.9 b/share/man/man9/VOP_ALLOCATE.9 index fce2ea183273..4fcbe773f236 100644 --- a/share/man/man9/VOP_ALLOCATE.9 +++ b/share/man/man9/VOP_ALLOCATE.9 @@ -45,7 +45,7 @@ .Sh DESCRIPTION This call allocates storage for a range of offsets in a file. It is used to implement the -.Xr posix_fallocate +.Xr posix_fallocate 2 system call. .Pp Its arguments are: diff --git a/share/man/man9/VOP_ATTRIB.9 b/share/man/man9/VOP_ATTRIB.9 index a3bf2c0f8898..d7c55bd683d8 100644 --- a/share/man/man9/VOP_ATTRIB.9 +++ b/share/man/man9/VOP_ATTRIB.9 @@ -37,12 +37,26 @@ .In sys/param.h .In sys/vnode.h .Ft int -.Fn VOP_GETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" +.Fo VOP_GETATTR +.Fa struct vnode *vp +.Fa flags +.Fa struct vattr *vap +.Fa struct ucred *cred +.Fc .Ft int -.Fn VOP_SETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" +.Fo VOP_SETATTR +.Fa struct vnode *vp +.Fa struct vattr *vap +.Fa struct ucred *cred +.Fc .Ft int -.Fn VOP_STAT "struct vnode *vp" "struct stat *sb" "struct ucred *active_cred" \ -"struct ucred *file_cred" +.Fo VOP_STAT +.Fa struct vnode *vp +.Fa struct stat *sb +.Fa flags +.Fa struct ucred *active_cred +.Fa struct ucred *file_cred +.Fc .Sh DESCRIPTION These entry points manipulate various attributes of a file or directory, including file permissions, owner, group, size, diff --git a/share/man/man9/VOP_INOTIFY.9 b/share/man/man9/VOP_INOTIFY.9 new file mode 100644 index 000000000000..43b644682153 --- /dev/null +++ b/share/man/man9/VOP_INOTIFY.9 @@ -0,0 +1,60 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Klara, Inc. +.\" +.Dd May 27, 2025 +.Dt VOP_INOTIFY 9 +.Os +.Sh NAME +.Nm VOP_INOTIFY +.Nd vnode inotify interface +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo VOP_INOTIFY +.Fa struct vnode *vp +.Fa struct vnode *dvp +.Fa struct componentname *cnp +.Fa int event +.Fa uint32_t cookie +.Fc +.Ft int +.Fo VOP_INOTIFY_ADD_WATCH +.Fa struct vnode *vp +.Fa struct inotify_softc *sc +.Fa uint32_t mask +.Fa uint32_t *wdp +.Fa struct thread *td +.Fc +.Sh DESCRIPTION +The +.Fn VOP_INOTIFY +operation notifies the +.Xr inotify 2 +subsystem of a file system event on a vnode. +The +.Fa dvp +and +.Fa cnp +arguments are optional and are only used to obtain a file name for the event. +If they are omitted, the inotify subsystem will use the file name cache to +find a name for the vnode, but this is more expensive. +.Pp +The +.Fn VOP_INOTIFY_ADD_WATCH +operation is for internal use by the inotify subsystem to add a watch to a +vnode. +.Sh LOCKS +The +.Fn VOP_INOTIFY +operation does not assume any particular vnode lock state. +The +.Fn VOP_INOTIFY_ADD_WATCH +operation should be called with the vnode locked. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh SEE ALSO +.Xr inotify 2 , +.Xr vnode 9 diff --git a/share/man/man9/VOP_READ_PGCACHE.9 b/share/man/man9/VOP_READ_PGCACHE.9 index f8f67eb00f13..8a99365eba28 100644 --- a/share/man/man9/VOP_READ_PGCACHE.9 +++ b/share/man/man9/VOP_READ_PGCACHE.9 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2021 The FreeBSD Foundation, Inc. +.\" Copyright (c) 2021 The FreeBSD Foundation .\" .\" This documentation was written by .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship diff --git a/share/man/man9/VOP_SETLABEL.9 b/share/man/man9/VOP_SETLABEL.9 index e5cf99bebd86..4ab7dd9beaba 100644 --- a/share/man/man9/VOP_SETLABEL.9 +++ b/share/man/man9/VOP_SETLABEL.9 @@ -113,13 +113,13 @@ Depending on the underlying implementation of .Fn VOP_SETLABEL , other errors may also be possible. .Sh SEE ALSO +.Xr mac 9 , +.Xr mount 9 , +.Xr vnode 9 , .Xr VOP_CLOSEEXTATTR 9 , .Xr VOP_OPENEXTATTR 9 , .Xr VOP_READEXTATTR 9 , -.Xr VOP_WRITEXTATTR 9 , -.Xr mac 9 , -.Xr mount 9 , -.Xr vnode 9 +.Xr VOP_WRITEXTATTR 9 .Sh AUTHORS This manual page was written by .An Robert Watson . diff --git a/share/man/man9/accf_http.9 b/share/man/man9/accf_http.9 index f48894807312..f71bb7811dc0 100644 --- a/share/man/man9/accf_http.9 +++ b/share/man/man9/accf_http.9 @@ -28,7 +28,7 @@ .Os .Sh NAME .Nm accf_http -.Nd "buffer incoming connections until a certain complete HTTP requests arrive" +.Nd "buffer incoming connections until a certain complete HTTP request arrives" .Sh SYNOPSIS .Nm options INET .Nm options ACCEPT_FILTER_HTTP diff --git a/share/man/man9/accf_tls.9 b/share/man/man9/accf_tls.9 index 331ea2aa4fb8..d4dbc299e5bb 100644 --- a/share/man/man9/accf_tls.9 +++ b/share/man/man9/accf_tls.9 @@ -26,7 +26,7 @@ .Os .Sh NAME .Nm accf_tls -.Nd "buffer incoming connections until a TLS handshake like requests arrive" +.Nd "buffer incoming connections until a TLS handshake like request arrives" .Sh SYNOPSIS .Nm options INET .Nm options ACCEPT_FILTER_TLS diff --git a/share/man/man9/atomic.9 b/share/man/man9/atomic.9 index 98d392dd6032..df24cd4a4d2b 100644 --- a/share/man/man9/atomic.9 +++ b/share/man/man9/atomic.9 @@ -20,7 +20,7 @@ .\" (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 16, 2023 +.Dd December 16, 2024 .Dt ATOMIC 9 .Os .Sh NAME @@ -60,7 +60,7 @@ .Ft void .Fn atomic_interrupt_fence "void" .Ft <type> -.Fn atomic_load_[acq_]<type> "volatile <type> *p" +.Fn atomic_load_[acq_]<type> "const volatile <type> *p" .Ft <type> .Fn atomic_readandclear_<type> "volatile <type> *p" .Ft void @@ -480,10 +480,14 @@ and .Fn atomic_testandclear functions are only implemented for the types .Dq Li int , -.Dq Li long +.Dq Li long , +.Dq ptr , +.Dq Li 32 , and -.Dq Li 32 -and do not have any variants with memory barriers at this time. +.Dq Li 64 +and generally do not have any variants with memory barriers at this time +except for +.Fn atomic_testandset_acq_long . .Pp The type .Dq Li 64 diff --git a/share/man/man9/bitset.9 b/share/man/man9/bitset.9 index a4e360a678d7..b77cfec63e26 100644 --- a/share/man/man9/bitset.9 +++ b/share/man/man9/bitset.9 @@ -193,7 +193,7 @@ These macros are meant to be used in the kernel and are visible if or .In sys/bitset.h are included in a program. -Userland programs must define +Userland programs must define .Dv _WANT_FREEBSD_BITSET before including these files to make the macros visible. .Pp diff --git a/share/man/man9/bus_attach_children.9 b/share/man/man9/bus_attach_children.9 new file mode 100644 index 000000000000..5e3ca4c5e906 --- /dev/null +++ b/share/man/man9/bus_attach_children.9 @@ -0,0 +1,152 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 John Baldwin <jhb@FreeBSD.org> +.Dd February 5, 2025 +.Dt BUS_ATTACH_CHILDREN 9 +.Os +.Sh NAME +.Nm bus_attach_children , +.Nm bus_delayed_attach_children , +.Nm bus_detach_children , +.Nm bus_enumerate_hinted_children , +.Nm bus_identify_children +.Nd manage child devices of a bus device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn bus_attach_children "device_t dev" +.Ft void +.Fn bus_delayed_attach_children "device_t bus" +.Ft int +.Fn bus_detach_children "device_t dev" +.Ft void +.Fn bus_enumerate_hinted_children "device_t bus" +.Ft void +.Fn bus_identify_children "device_t dev" +.Sh DESCRIPTION +These functions manage state transitions of child devices for +.Fa dev . +.Pp +.Fn bus_enumerate_hinted_children +walks the kernel environment to identify any device hints that describe a +device attached to +.Fa dev . +For each set of matching hints, +the +.Xr BUS_HINTED_CHILD 9 +method is invoked. +This function is typically called from a bus driver's +.Xr DEVICE_ATTACH 9 +method to add hinted devices. +Note that most bus drivers do not use hints to identify child devices. +This is typically used for legacy buses such as ISA that do not provide +a mechanism for enumerating devices. +.Pp +.Fn bus_identify_children +iterates over all eligible device drivers for children of +.Fa dev +invoking the +.Xr DEVICE_IDENTIFY 9 +method. +This allows device drivers to add child devices that are enumerated via +alternate mechanisms such as firmware tables. +This function is typically called from a bus driver's +.Xr DEVICE_ATTACH 9 +method. +.Pp +.Fn bus_attach_children +attaches device drivers to all children of +.Fa dev . +This function invokes +.Xr device_probe_and_attach 9 +on each child device ignoring errors. +It makes a best-effort pass to attach device drivers to all children. +Child devices are attached in increasing order. +Child devices with the same order are attached in FIFO order based +on the time when the device was created via +.Xr device_add_child 9 . +This function is typically called from a bus driver's +.Xr DEVICE_ATTACH 9 +method after adding devices. +.Pp +.Fn bus_delayed_attach_children +attaches device drivers to all children of +.Fa dev +after interrupts are enabled. +This function schedules a call to +.Fn bus_attach_children +after interrupts are enabled via +.Xr config_intrhook_establish 9 . +If interrupts are already enabled +(for example, when loading a device driver after booting), +.Fn bus_attach_children +is called immediately. +.Pp +.Fn bus_detach_children +detaches device drivers from all children of +.Fa dev +by calling +.Xr device_detach 9 +on each child device. +Unlike +.Fn bus_attach_children , +this function does not make a best-effort pass. +If a child device fails to detach, +.Fn bus_detach_children +immediately fails returning the error from the child's failed detach. +Child devices are detached in reverse order compared to +.Fn bus_attach_children . +That is, +child devices are detached in decreasing order, +and child devices with the same order are detached in LIFO order. +Detached devices are not deleted. +.Pp +.Fn bus_detach_children +is typically called at the start of a bus driver's +.Xr DEVICE_ATTACH 9 +method to give child devices a chance to veto the detach request. +It is usually paired with a later call to +.Fn device_delete_children 9 +to delete child devices. +If no additional logic is required between the two function calls, +a bus driver can use +.Xr bus_generic_detach 9 +to detach and delete children. +.Sh RETURN VALUES +.Sh SEE ALSO +.Xr config_intrhook_establish 9 , +.Xr device_add_child 9 , +.Xr DEVICE_ATTACH 9 , +.Xr device_delete_children 9 , +.Xr DEVICE_DETACH 9 , +.Xr device_detach 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr device_probe_and_attach 9 +.Sh HISTORY +.Fn bus_enumerate_hinted_children +first appeared in +.Fx 6.2 . +.Pp +.Fn bus_delayed_attach_children +first appeared in +.Fx 12.2 . +.Pp +.Fn bus_identify_children +first appeared in +.Fx 15.0 . +Its functionality is available in older releases via the deprecated +.Fn bus_generic_probe . +.Pp +.Fn bus_attach_children +first appeared in +.Fx 15.0 . +Its functionality is available in older releases via the deprecated +.Fn bus_generic_attach . +.Pp +.Fn bus_detach_children +first appeared in +.Fx 15.0 . +Its functionality is available in older releases via +.Fn bus_generic_detach . diff --git a/share/man/man9/bus_delayed_attach_children.9 b/share/man/man9/bus_delayed_attach_children.9 deleted file mode 100644 index 40a7357831a5..000000000000 --- a/share/man/man9/bus_delayed_attach_children.9 +++ /dev/null @@ -1,53 +0,0 @@ -.\" -*- nroff -*- -.\" -.\" Copyright (c) 2019 M. Warner Losh -.\" -.\" 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 DEVELOPERS ``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 DEVELOPERS 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 December 13, 2019 -.Dt BUS_DELAYED_ATTACH_CHILDREN 9 -.Os -.Sh NAME -.Nm bus_delayed_attach_children -.Nd "request that the children be attached when interrupts are enabled" -.Sh SYNOPSIS -.In sys/param.h -.In sys/bus.h -.Pp -.Ft int -.Fn bus_delayed_attach_children "device_t dev" -.Sh DESCRIPTION -The -.Fn bus_delayed_attach_children -function requests that the children of this device -be attached when interrupts are running. -If interrupts are currently running, this happens immediately. -If interrupts are not yet running, this happens after interrupts are enabled, but -before the system mounts root. -.Sh RETURN VALUES -A zero return value indicates success. -.Sh SEE ALSO -.Xr bus 9 , -.Xr device 9 , -.Xr driver 9 -.Sh AUTHORS -This manual page was written by -.An Warner Losh Aq Mt imp@FreeBSD.org . diff --git a/share/man/man9/bus_generic_attach.9 b/share/man/man9/bus_generic_attach.9 deleted file mode 100644 index 67d125c2943c..000000000000 --- a/share/man/man9/bus_generic_attach.9 +++ /dev/null @@ -1,56 +0,0 @@ -.\" -*- nroff -*- -.\" -.\" Copyright (c) 1998 Doug Rabson -.\" -.\" All rights reserved. -.\" -.\" This program is free software. -.\" -.\" 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 DEVELOPERS ``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 DEVELOPERS 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 15, 2017 -.Dt BUS_GENERIC_ATTACH 9 -.Os -.Sh NAME -.Nm bus_generic_attach -.Nd generic implementation of -.Dv DEVICE_ATTACH -for buses -.Sh SYNOPSIS -.In sys/param.h -.In sys/bus.h -.Ft int -.Fn bus_generic_attach "device_t dev" -.Sh DESCRIPTION -This function provides an implementation of the -.Xr DEVICE_ATTACH 9 -method which can be used by most bus code. -It simply calls -.Xr device_probe_and_attach 9 -for each child device attached to the bus. -.Sh RETURN VALUES -Zero is returned on success, otherwise an appropriate error is returned. -.Sh SEE ALSO -.Xr device 9 , -.Xr driver 9 -.Sh AUTHORS -This manual page was written by -.An Doug Rabson . diff --git a/share/man/man9/bus_generic_detach.9 b/share/man/man9/bus_generic_detach.9 index 590cd26486e4..b7a2aa6e6105 100644 --- a/share/man/man9/bus_generic_detach.9 +++ b/share/man/man9/bus_generic_detach.9 @@ -26,7 +26,7 @@ .\" (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 15, 2017 +.Dd February 5, 2025 .Dt BUS_GENERIC_DETACH 9 .Os .Sh NAME @@ -44,13 +44,23 @@ This function provides an implementation of the .Xr DEVICE_DETACH 9 method which can be used by most bus code. -It simply calls the -.Xr DEVICE_DETACH 9 -method of each child device attached to the bus. +It uses +.Xr bus_detach_children 9 +to detach drivers from all child devices giving them a chance to veto the +detach request. +If +.Fn bus_detach_children +succeeds, +.Fn bus_generic_detach +calls +.Xr device_delete_children 9 +to delete all child devices. .Sh RETURN VALUES Zero is returned on success, otherwise an appropriate error is returned. .Sh SEE ALSO +.Xr bus_detach_children 9 , .Xr device 9 , +.Xr device_delete_children 9 , .Xr driver 9 .Sh AUTHORS This manual page was written by diff --git a/share/man/man9/bus_generic_print_child.9 b/share/man/man9/bus_generic_print_child.9 index 8c3bd4b0fc71..8a72c8e743ec 100644 --- a/share/man/man9/bus_generic_print_child.9 +++ b/share/man/man9/bus_generic_print_child.9 @@ -26,37 +26,88 @@ .\" (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 15, 2017 +.Dd February 5, 2025 .Dt BUS_GENERIC_PRINT_CHILD 9 .Os .Sh NAME -.Nm bus_generic_print_child +.Nm bus_generic_print_child , +.Nm bus_print_child_domain , +.Nm bus_print_child_footer , +.Nm bus_print_child_header .Nd generic implementation of -.Dv DEVICE_PRINT_CHILD -for buses +.Xr BUS_PRINT_CHILD 9 .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft int .Fn bus_generic_print_child "device_t dev" "device_t child" +.Ft int +.Fn bus_print_child_domain "device_t dev" "device_t child" +.Ft int +.Fn bus_print_child_footer "device_t dev" "device_t child" +.Ft int +.Fn bus_print_child_header "device_t dev" "device_t child" .Sh DESCRIPTION -This implementation prints out the default device announcement message. -Given device 'foo0' on bus 'bar0' where foo0 has the name "FooCard 1234" the +.Fn bus_generic_print_child +prints out the default device announcement message. +Given device +.Sq foo0 +on bus +.Sq bar0 +where foo0 has the description +.Dq FooCard 1234 +and is associated with the NUMA domain 1, +the following would be printed: +.Bd -literal -offset indent +foo0: <FooCard 1234> numa-domain 1 on bar0 +.Ed .Pp -foo0: <FooCard 1234> on bar0 -.Pp -bus_generic_print_child itself calls two functions -.Fn bus_print_child_header +.Fn bus_generic_print_child +calls the three helper functions +.Fn bus_print_child_header , +.Fn bus_print_child_domain , and .Fn bus_print_child_footer . -The former prints "foo0: <FooCard 1234>" and the latter "on bar0". -These routines should be used if possible in your own code if +.Pp +.Fn bus_print_child_header +outputs the device name and unit followed by the device description +in angle brackets +.Po +.Dq foo0: <FooCard 1234> +.Pc . +.Pp +.Fn bus_print_child_domain +outputs +.Dq \& numa-domain +followed by the domain number if +.Fn bus_get_domain +returns a valid domain for the device +.Po +.Dq numa-domain 1 +.Pc . +If +.Fa dev +is not associated witha valid domain, +nothing is output. +.Pp +.Fn bus_print_child_footer +outputs the string +.Dq \& on +followed by the parent device's name and unit +.Po +.Dq \& on bar0 +.Pc . +.Pp +These functions can be used to implement +.Xr BUS_PRINT_CHILD 9 +in a bus driver if .Fn bus_generic_print_child -does not completely suit your needs. +is not sufficient. .Sh RETURN VALUES The number of characters output. .Sh SEE ALSO +.Xr BUS_PRINT_CHILD 9 , .Xr device 9 .Sh AUTHORS This manual page was written by diff --git a/share/man/man9/cdefs.9 b/share/man/man9/cdefs.9 new file mode 100644 index 000000000000..cc56e34d070a --- /dev/null +++ b/share/man/man9/cdefs.9 @@ -0,0 +1,487 @@ +.\"- +.\" Copyright (c) 2024 M. Warner Losh <imp@FreeBSD.org> +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd May 9, 2025 +.Dt CDEFS 9 +.Os +.Sh NAME +.Nm cdefs +.Nd compiler portability macro definitions +.Sh DESCRIPTION +.In sys/cdefs.h +defines macros for compiler, C language standard portability, POSIX standards +compliance and symbol visibility. +It defines programming interfaces for the system header files to adopt to the +many environments +.Fx +supports compilation for. +It defines convenience macros for the +.Fx +sources, tailored to the base +system's needs. +.Pp +Most of these macros are for use inside the +.Fx +sources only. +They are not intended as a general portability layer. +.Sh Supported Compilers +.Bl -tag -offset 2n -width 0 +.It Compilers supported for building programs on Fx : +.Bl -column -offset 0n indent-two +.It Sy Compiler Ta Sy Versions +.It gcc Ta 9, 10, 11, 12, 13, 14 +.It clang Ta 10, 11, 12, 13, 14, 15, 16, 17, 18 +.It TinyC (tcc) Ta 0.9 +.It pcc Ta 1.1 +.El +.Pp +Due to testing constraints, tcc and pcc may not always work. +.It Compilers supported for building Fx itself: +.Bl -column -offset 0n indent-two +.It Sy Compiler Ta Sy Major Versions Supported +.It gcc Ta 12, 13, 14 +.It clang Ta 16, 17, 18 +.El +.Pp +Please note: Not every single minor versions of these compilers +will work or are supported. +.El +.Sh Macros and Magic for Programming Environment +.Nm +defines (or refrains from defining) a number of macros to increase portability +of compiled programs. +These are to allow more advanced language features to appear in header files. +The header files assume a compiler that accepts C prototype function +declarations. +They also assume that the compiler accepts ANSI C89 keywords for all language +dialects. +.Ss General Macros +General macros that facilitate multiple language environments and language +dialects. +.Bl -column "---------------" +.It Sy Macro Ta Sy Description +.It Dv __volatile Ta expands to volatile in C++ and C89 and newer environments, +__volatile in pre-ANSI environments that support this extension or nothing +otherwise. +.It Dv __inline Ta expands to inline in C++ and C89 and newer environments, +__inline in pre-ANSI environments that support this extension or nothing +otherwise. +.It Dv __restrict Ta expands to restrict in C99 and newer environments, or +__restrict otherwise. +.It Dv __CONCAT Ta used to paste two pre-processor tokens. +.It Dv __STRING Ta used to convert the argument to a string. +.It Dv __BEGIN_DECLS Ta Start a group of functions. +.It Dv __END_DECLS Ta End a group of functions. +In a C environment, these are defined as nothing. +In a C++ environment, these declare the functions to have +.Dq C +linkage. +.El +.Ss Function, Structure and Variable Modifiers +.Bl -column "---------------" +.It Sy Macro Ta Sy Description +.It Sy __weak_symbol Ta Declare the symbol to be a weak symbol +.It Sy __dead2 Ta Function will not return +.It Sy __pure2 Ta Function has no side effects +.It Sy __unused Ta To Variable may be unused (usually arguments), so do not +warn about it +.It Sy __used Ta Function really is used, so emit it even if it appears unused. +.It Sy __deprecated Ta Function interface has been deprecated, and clients +should migrate to a new interface. +A warning will be issued for clients of this interface. +.It Sy __deprecated1(msg) Ta Function interface has been deprecated, and clients +should migrate to a new interface. +The string +.Fa msg +will be included in a warning issued for clients of this interface. +.It Sy __packed Ta \&Do not have space between structure elements for natural alignment. +Used when communicating with external protocols. +.It Sy __aligned(x) Ta Specify in bytes the minimum alignment for the specified field, structure or variable +.It Sy __section(x) Ta Place function or variable in section Fa x +.It Sy __writeonly Ta Hint that the variable is only assigned to, but do not warn about it. +Useful for macros and other places the eventual use of the result is unknown. +.It Sy __alloc_size(x) Ta The function always returns at least the number of +bytes determined by argument number Fa x +.It Sy __alloc_size2(x,n) Ta The function always returns an array, whose size +is at least the number of bytes determined by argument number Fa x times the +number of elements specified by argument number Fa n +.It Sy __alloc_align(x) Ta Function either returns a pointer aligned to Fa x bytes +or Dv NULL. +.It Sy __min_size Ta Declare the array to have a certain, minimum size +.It Sy __malloc_like Ta Function behaves like the +.Dq malloc +family of functions. +.It Sy __pure Ta Function has no side effects +.It Sy __always_inline Ta Always inline this function when called +.It Sy __fastcall Ta Use the +.Dq fastcall +ABI to call and name mangle this function. +.It Sy __result_use_check Ta Warn if function caller does not use its return value +.It Sy __nodiscard Ta Equivalent to the standard +.Dq [[nodiscard]] +attribute. +If applied to a function, warn if function caller does not use its +return value. +The warning may be silenced using a cast to +.Vt void , +or in C++, using an assignment to +.Va std::ignore . +If applied to a struct, C++ class or enum, this applies to all functions +returning values of that type. +If applied to a C++ constructor, this applies to creating instances of +the class using that constructor. +.It Sy __returns_twice Ta Returns multiple times, like +.Xr fork 2 +.It Sy __unreachable Ta This code is not reachable at runtime +.It Sy __predict_true(x) Ta Hint to the compiler that +.Fa x +is true most of the time. +Should only be used when performance is improved for a frequently called bit of code. +.It Sy __predict_false(x) Ta Hint to the compiler that +.Fa x +is false most of the time. +Should only be used when performance is improved for a frequently called bit of code. +.It Sy __null_sentinel Ta The varadic function contains a parameter that is +a NULL sentinel to mark the end of its arguments. +.It Sy __exported Ta +.It Sy __hidden Ta +.It Sy __printflike(fmtarg,firstvararg) Ta Function is similar to +.Fn printf +which specifies the format argument with +.Fa fmtarg +and where the arguments formatted by that format start with the +.Fa firstvararg , +with 0 meaning that +.Dv va_arg +is used and cannot be checked. +.It Sy __scanflike(fmtarg,firstvararg) Ta Function is similar to +.Fn scanf +which specifies the format argument with +.Fa fmtarg +and where the arguments formatted by that format start with the +.Fa firstvararg , +with 0 meaning that +.Dv va_arg +is used and cannot be checked. +.It Sy __format_arg(f) Ta Specifies that arg +.Fa f +contains a string that will be passed to a function like +.Fn printf +or +.Fa scanf +after being translated in some way. +.It Sy __strfmonlike(fmtarg,firstvararg) Ta Function is similar to +.Fn scanf +which specifies the format argument with +.Fa fmtarg +and where the arguments formatted by that format start with the +.Fa firstvararg , +with 0 meaning that +.Dv va_arg +is used and cannot be checked. +.It Sy __strtimelike(fmtarg,firstvararg) Ta Function is similar to +.Fn scanf +which specifies the format argument with +.Fa fmtarg +and where the arguments formatted by that format start with the +.Fa firstvararg , +with 0 meaning that +.Dv va_arg +is used and cannot be checked. +.It Sy __printf0like(fmtarg,firstvararg) Ta Exactly the same +as +.Sy __printflike +except +.Fa fmtarg +may be +.Dv NULL. +.It Sy __strong_reference(sym,aliassym) Ta +.It Sy __weak_reference(sym,alias) Ta +.It Sy __warn_references(sym,msg) Ta +.It Sy __sym_compat(sym,impl,verid) Ta +.It Sy __sym_default(sym,impl,verid) Ta +.It Sy __GLOBAL(sym) Ta +.It Sy __WEAK(sym) Ta +.It Sy __DECONST(type,var) Ta +.It Sy __DEVOLATILE(type,var) Ta +.It Sy __DEQUALIFY(type,var) Ta +.It Sy __RENAME(x) Ta +.It Sy __arg_type_tag Ta +.It Sy __datatype_type_tag Ta +.It Sy __align_up(x,y) Ta +.It Sy __align_down(x,y) Ta +.It Sy __is_aligned(x,y) Ta +.El +.Ss Locking and Debugging Macros +Macros for lock annotation and debugging, as well as some general debugging +macros for address sanitizers. +.Bl -column "---------------" +.It Sy __lock_annotate(x) Ta +.It Sy __lockable Ta +.It Sy __locks_exclusive Ta +.It Sy __locks_shared Ta +.It Sy __trylocks_exclusive Ta +.It Sy __trylocks_shared Ta +.It Sy __unlocks Ta +.It Sy __asserts_exclusive Ta +.It Sy __asserts_shared Ta +.It Sy __requires_exclusive Ta +.It Sy __requires_shared Ta +.It Sy __requires_unlocked Ta +.It Sy __no_lock_analysis Ta +.It Sy __nosanitizeaddress Ta +.It Sy __nosanitizememory Ta +.It Sy __nosanitizethread Ta +.It Sy __nostackprotector Ta +.It Sy __guarded_by(x) Ta +.It Sy __pt_guarded_by(x) Ta +.El +.Ss Emulated Keywords +As C evolves, many of the old macros we once used have been incorporated into +the standard language. +As this happens, we add support for these keywords as macros for older +compilation environments. +Sometimes this results in a nop in the older environment. +.Bl -column "---------------" +.It Sy Keyword Ta Sy Description +.It Sy _Alignas(x) Ta +.It Sy _Alignof(x) Ta +.It Sy _Noreturn Ta Expands to +.Dq [[noreturn]] +in C++-11 and newer compilation environments, otherwise +.Dq __dead2 +.It Sy _Static_assert(x, y) Ta Compile time assertion that +.Fa x +is true, otherwise emit +.Fa y +as the error message. +.It Sy _Thread_local Ta Designate variable as thread local storage +.It Sy __generic Ta implement _Generic-like features which aren't entirely possible to emulate the _Generic keyword +.It Sy __noexcept Ta to emulate the C++11 argument-less noexcept form +.It Sy __noexcept_if Ta to emulate the C++11 conditional noexcept form +.It Sy _Nonnull Ta +.It Sy _Nullable Ta +.It Sy _Null_unspecified Ta +.El +.Ss Support Macros +The following macros are defined, or have specific values, to denote certain +things about the build environment. +.Bl -column "---------------" +.It Sy Macro Ta Sy Description +.It Sy __LONG_LONG_SUPPORTED Ta Variables may be declared +.Dq long long . +This is defined for C99 or newer and C++ environments. +.It Sy __STDC_LIMIT_MACROS Ta +.It Sy __STDC_CONSTANT_MACROS Ta +.El +.Ss Convenience Macros +These macros make it easier to do a number of things, even though strictly +speaking the standard places their normal form in another header. +.Bl -column "---------------" +.It Sy Macro Ta Sy Description +.It Sy __offsetof(type,field) Ta +.It Sy __rangeof(type,start,end) Ta +.It Sy __containerof(x,s,m) Ta +.El +.Ss ID Strings +This section is deprecated, but is kept around because too much contrib software +still uses these. +.Bl -column "---------------" +.It Sy Macro Ta Sy Description +.It Sy __IDSTRING(name,string) Ta +.It Sy __FBSDID(s) Ta +.It Sy __RCSID(s) Ta +.It Sy __RCSID_SOURCE(s) Ta +.It Sy __SCCSID(s) Ta +.It Sy __COPYRIGHT(s) Ta +.El +.Sh Supported C Environments +.Fx +supports a number C standard environments. +Selection of the language dialect is a compiler-dependent command line option, +though it is usually +.Fl std=XX +where XX is the standard to set for compiling, such as c89 or c23. +.Fx +provides a number of selection macros to control visibility of symbols. +Please see the section on Selection Macros for the specifics. +.Pp +.Bl -tag +.It K \*(Am R +Pre-ANSI Kernighan and Ritchie C. +Sometimes called +.Dq knr +or +.Dq C78 +to distinguish it from newer standards. +Support for this compilation environment is dependent on compilers supporting +this configuration. +Most of the old forms of C have been deprecated or removed in +.St -isoC-2023 . +Compilers make compiling in this mode increasingly difficult and support for it +may ultimately be removed from the tree. +.It St -ansiC +.Dv __STDC__ +is defined, however +.Dv __STDC_VERSION__ +is not. +.Pp +Strict environment selected with +.Dv _ANSI_SOURCE . +.It St -isoC-99 +.Dv __STDC_VERSION__ = 199901L +.Pp +Strict environment selected with +.Dv _C99_SOURCE . +.It St -isoC-2011 +.Dv __STDC_VERSION__ = 201112L +.Pp +Strict environment selected with +.Dv _C11_SOURCE . +.It ISO/IEC 9899:2018 (“ISO C17”) +.Dv __STDC_VERSION__ = 201710L +.Pp +Strict environment selected with +.Dv _C11_SOURCE +since there are no new C17 only symbols or macros. +.Pp +This version of the standard did not introduce any new features, only made +minor, technical corrections. +.It St -isoC-2023 +.Dv __STDC_VERSION__ = 202311L +Strict environment selected with +.Dv _C23_SOURCE +though ISO C23 support is only partially implemented. +.El +.Pp +For more information on C standards, see +.Xr c 7 . +.Ss Programming Environment Selection Macros +Defining the macros outlined below requests that the system header files provide +only the functions, structures and macros (symbols) defined by the appropriate +standard, while suppressing all extensions. +However, system headers not defined by that standard may define extensions. +You may only define one of the following for any compilation unit. +.Bl -column "---------------" +.It Sy Macro Ta Sy Environment +.It Dv _POSIX_SOURCE Ta St -p1003.1-88 including St -ansiC +.It Dv _POSIX_C_SOURCE = 1 Ta St -p1003.1-88 including St -ansiC +.It Dv _POSIX_C_SOURCE = 2 Ta St -p1003.1-90 including St -ansiC +.It Dv _POSIX_C_SOURCE = 199309 Ta St -p1003.1b-93 including St -ansiC +.It Dv _POSIX_C_SOURCE = 199506 Ta St -p1003.1c-95 including St -ansiC +.It Dv _POSIX_C_SOURCE = 200112 Ta St -p1003.1-2001 including St -isoC-99 +.It Dv _POSIX_C_SOURCE = 200809 Ta St -p1003.1-2008 including St -isoC-99 +.It Dv _POSIX_C_SOURCE = 202405 Ta St -p1003.1-2024 including ISO/IEC 9899:2018 ("ISO C17"), +.It Dv _XOPEN_SOURCE defined Ta St -p1003.1-90 with XPG Extensions to St -susv1 including St -ansiC . +However, +.Fx +implements this as a NOP because too much software breaks with the correct strict environment. +.It Dv _XOPEN_SOURCE = 500 Ta St -p1003.1c-95 and XPG extensions to St -susv2 including St -ansiC +.It Dv _XOPEN_SOURCE = 600 Ta St -p1003.1-2001 and XPG extensions to St -susv3 including St -isoC-99 +.It Dv _XOPEN_SOURCE = 700 Ta St -p1003.1-2008 and XPG extensions to St -susv4 including St -isoC-99 +.It Dv _XOPEN_SOURCE = 800 Ta St -p1003.1-2024 and XPG extensions to Version 5 of the Single UNIX Specification (“SUSv5”) including ISO/IEC 9899:2018 (“ISO C17”) +.It Dv _ANSI_SOURCE Ta St -ansiC +.It Dv _C99_SOURCE Ta St -isoC-99 +.It Dv _C11_SOURCE Ta St -isoC-2011 +.It Dv _C23_SOURCE Ta St -isoC-2023 +.It Dv _BSD_SOURCE Ta Everything, including Fx extensions +.El +.Pp +Note: +.St -p1003.1-2024 +and XPG extensions to Version 5 of the Single UNIX Specification ("SUSv5") +support is incomplete. +.Pp +When both POSIX and C environments are selected, the POSIX environment selects +which C environment is used. +However, when C11 dialect is selected with +.St -p1003.1-2008 , +definitions for +.St -isoC-2011 +are also included. +Likewise, when C23 dialog is selected with +.St -p1003.1-2008 +or +.St -p1003.1-2024 , +definitions for +.St -isoC-2023 +are also included. +.Ss Header Visibility Macros +These macros are set by +.Nm +to control the visibility of different standards. +Users must not define these, and doing so will produced undefined results. +They are documented here for developers working on system's header files. +.Bl -column "---------------" +.It Dv __XSI_VISIBLE Ta Restricts the visibility of XOPEN Single Unix Standard version. +Possible values are 500, 600, 700 or 800, corresponding to Issue 5, 6, 7, or 8 +of the Single Unix Standard. +These are extra functions in addition to the normal POSIX ones. +.It Dv __POSIX_VISIBLE Ta Make symbols associated with certain standards versions visible. +Set to the value assigned to +.Dv _POSIX_C_SOURCE +by convention with 199009 for +.St -p1003.1-88 +and 199209 +.St -p1003.1-90 . +.It Dv __ISO_C_VISIBLE Ta The C level that's visible. +Possible values include 1990, 1999, 2011, 2017 and 2023 for +.St -isoC-90 , +.St -isoC-99 , +.St -isoC-2011 , +ISO/IEC 9899:2018 ("ISO C17"), and +.St -isoC-2023 , +respectively. +.It Dv __BSD_VISIBLE Ta 1 if the +.Fx +extensions are visible, 0 otherwise. +.It Dv __EXT1_VISIBLE Ta 1 if the +.St -isoC-2011 +Appendix K 3.7.4.1 +extensions are visible, 0 otherwise. +.El +.Sh Supported C++ Environments +.Fx +supports C++11 and newer standards fully. +.Bl -tag +.It ISO/IEC 14882:1998 ("C++98") +.Dv __cplusplus = 199711 +.Pp +The first standardized version of C++. +Unlike K \*(Am R support in C, compilers dropped support for versions of +the language prior to C++98. +.It ISO/IEC 14882:2003 ("C++03") +.Dv __cplusplus = 199711 +.Pp +Note, this is the same value as C++98. +C++03 did not define a new value for +.Dv __cplusplus . +There is no way, at compile time, to detect the difference. +The standard resolved a number of defect reports and slightly +expanded value initialization. +Most compilers support it the same as C++98. +.It ISO/IEC 14882:2011 ("C++11") +.Dv __cplusplus = 201103 +.It ISO/IEC 14882:2014 ("C++14") +.Dv __cplusplus = 201402 +.It ISO/IEC 14882:2017 ("C++17") +.Dv __cplusplus = 201703 +.It ISO/IEC 14882:2020 ("C++20") +.Dv __cplusplus = 202002 +.It ISO/IEC 14882:2023 ("C++23") +.Dv __cplusplus = 202302 +.El +.Pp +.Fx +uses llvm project's libc++. +However, they are removing support for C++ prior to C++11. +While programs can still build with earlier environments for now, these changes +mean that +.Fl pedantic-errors +cannot be reliably enabled for standards older than C++11. +.Sh HISTORY +.In sys/cdefs.h +first appeared in +.Bx 4.3 NET/2 . diff --git a/share/man/man9/cnv.9 b/share/man/man9/cnv.9 index de37c8271eb9..fa5310e174e1 100644 --- a/share/man/man9/cnv.9 +++ b/share/man/man9/cnv.9 @@ -23,14 +23,14 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd June 18, 2018 +.Dd January 3, 2025 .Dt CNV 9 .Os .Sh NAME .Nm cnvlist_get , .Nm cnvlist_take , .Nm cnvlist_free -.Nd "API for managing name/value pairs by cookie." +.Nd "API for managing name/value pairs by cookie" .Sh LIBRARY .Lb libnv .Sh SYNOPSIS @@ -115,7 +115,7 @@ The .Nm libnv library permits easy management of name/value pairs and can send and receive them over sockets. -For more information, also see +For more information, see .Xr nv 9 . .Pp The concept of cookies is explained in @@ -128,25 +128,28 @@ from .Pp The .Fn cnvlist_name -function returns the name of an element associated with the given cookie. +function returns the name of an element associated with +.Fa cookie . .Pp The .Fn cnvlist_type -function returns the type of an element associated with the given cookie. +function returns the type of an element associated with +.Fa cookie . Types which can be returned are described in .Xr nv 9 . .Pp The .Nm cnvlist_get -family of functions obtains the value associated with the given cookie. +functions return the value associated with +.Fa cookie . Returned strings, nvlists, descriptors, binaries, or arrays must not be modified -by the user, since they still belong to the nvlist. +by the user since they still belong to the nvlist. The nvlist must not be in an error state. .Pp The .Nm cnvlist_take -family of functions returns the value associated with the given cookie and -removes the element from the nvlist. +functions return the value associated with the given cookie and +remove the element from the nvlist. When the value is a string, binary, or array value, the caller is responsible for freeing the returned memory with .Fn free 3 . @@ -154,18 +157,21 @@ When the value is an nvlist, the caller is responsible for destroying the returned nvlist with .Fn nvlist_destroy . When the value is a descriptor, the caller is responsible for closing the -returned descriptor with the +returned descriptor with .Fn close 2 . .Pp The .Nm cnvlist_free -family of functions removes an element of the supplied cookie and frees all -resources. -If an element of the given cookie has the wrong type or does not exist, the +functions remove the element identified by +.Fa cookie +and free any associated resources. +If the element identified by +.Fa cookie +has the wrong type or does not exist, the program -is aborted. +aborts. .Sh EXAMPLES -The following example demonstrates how to deal with cnvlist API. +The following example demonstrates how to deal with the cnvlist API. .Bd -literal int type; void *cookie, *scookie, *bcookie; diff --git a/share/man/man9/contigmalloc.9 b/share/man/man9/contigmalloc.9 index f52cb7bde0ed..2e5d55ae8ba1 100644 --- a/share/man/man9/contigmalloc.9 +++ b/share/man/man9/contigmalloc.9 @@ -23,11 +23,11 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd October 30, 2018 +.Dd July 26, 2024 .Dt CONTIGMALLOC 9 .Os .Sh NAME -.Nm contigmalloc , contigfree +.Nm contigmalloc .Nd manage contiguous kernel physical memory .Sh SYNOPSIS .In sys/types.h @@ -42,12 +42,6 @@ .Fa "unsigned long alignment" .Fa "vm_paddr_t boundary" .Fc -.Ft void -.Fo contigfree -.Fa "void *addr" -.Fa "unsigned long size" -.Fa "struct malloc_type *type" -.Fc .In sys/param.h .In sys/domainset.h .Ft "void *" @@ -109,10 +103,10 @@ Other flags (if present) are ignored. .Pp The .Fn contigfree -function deallocates memory allocated by a previous call to -.Fn contigmalloc -or -.Fn contigmalloc_domainset . +function is deprecated. +Use +.Xr free 9 +instead. .Sh IMPLEMENTATION NOTES The .Fn contigmalloc @@ -123,12 +117,6 @@ However, unless is specified, it may select a page for reclamation that must first be written to backing storage, causing it to sleep. .Pp -The -.Fn contigfree -function does not accept -.Dv NULL -as an address input, unlike -.Xr free 9 . .Sh RETURN VALUES The .Fn contigmalloc diff --git a/share/man/man9/coredumper_register.9 b/share/man/man9/coredumper_register.9 new file mode 100644 index 000000000000..f4c9eb4a1bf6 --- /dev/null +++ b/share/man/man9/coredumper_register.9 @@ -0,0 +1,168 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Kyle Evans <kevans@FreeBSD.org> +.\" +.Dd July 23, 2025 +.Dt COREDUMPER_REGISTER 9 +.Os +.Sh NAME +.Nm coredumper_register , +.Nm coredumper_unregister +.Nd loadable user coredumper support +.Sh SYNOPSIS +.In sys/ucoredump.h +.Ft void +.Fn coredumper_register "struct coredumper *cd" +.Ft void +.Fn coredumper_unregister "struct coredumper *cd" +.Pp +.Ft int +.Fn coredumper_probe_fn "struct thread *td" +.Ft int +.Fn coredumper_handle_fn "struct thread *td" "off_t limit" +.Bd -literal +/* Incomplete, but the useful members are depicted here. */ +struct coredumper { + const char *cd_name; + coredumper_probe_fn *cd_probe; + coredumper_handle_fn *cd_handle; +}; +.Ed +.Pp +.Ft int +.Fn coredump_init_fn "const struct coredump_writer *" \ +"const struct coredump_params *" +.Ft int +.Fn coredump_write_fn "const struct coredump_writer *" "const void *" "size_t" \ +"off_t" "enum uio_seg" "struct ucred *" "size_t *" "struct thread *" +.Ft int +.Fn coredump_extend_fn "const struct coredump_writer *" "off_t" "struct ucred *" +.Bd -literal +struct coredump_writer { + void *ctx; + coredump_init_fn *init_fn; + coredump_write_fn *write_fn; + coredump_extend_fn *extend_fn; +}; +.Ed +.Sh DESCRIPTION +The +.Nm +mechanism provides a path for kernel modules to register a new user process core +dumper. +The expected use of +.Nm +is for a module to define the fields of the struct coredumper listed above, then +call +.Fn coredumper_register +at +.Dv MOD_LOAD +time. +A corresponding +.Fn coredumper_unregister +should be called at +.Dv MOD_UNLOAD +time. +Note that +.Fn coredumper_unregister +will block until the specified coredumper is no longer processing coredumps. +.Pp +When a user process is preparing to start dumping core, the kernel will execute +the +.Fn cd_probe +function for each coredumper currently registered. +The +.Fn cd_probe +function is expected to return either -1 if it would decline to dump the +process, or a priority level greater than 0. +The coredumper with the highest priority will handle the coredump. +The following default priorities are defined: +.Bl -tag -width indent +.It Dv COREDUMPER_NOMATCH +This dumper declines dumping the process. +.It Dv COREDUMPER_GENERIC +This dumper will dump the process at the lowest priority. +This priority is not recommended, as the default vnode dumper will bid at +.Dv COREDUMPER_GENERIC +as well. +.It Dv COREDUMPER_SPECIAL +This dumper provides special behavior, and will dump the process at a higher +priority. +.It Dv COREDUMPER_HIGHPRIORITY +This dumper would prefer to handle this coredump. +This may be used by, for instance, a custom or vendor-specific coredump +mechanism that wishes to preempt others. +.El +.Pp +Note that this system has been designed such that the +.Fn cd_probe +function can examine the process in question and make an informed decision. +Different processes being dumped could probe at different priorities in the +same coredumper. +.Pp +Once the highest priority coredumper has been selected, the +.Fn cd_handle +function will be invoked. +The +.Fn cd_handle +will receive both the thread and the +.Dv RLIMIT_CORE +.Xr setrlimit 2 +.Fa limit . +The proc lock will be held on entry, and should be unlocked before the handler +returns. +The +.Fa limit +is typically passed to the +.Fn sv_coredump +that belongs to the process's +.Va p_sysent . +.Pp +The +.Fn cd_handle +function should return either 0 if the dump was successful, or an appropriate +.Xr errno 2 +otherwise. +.Ss Customized Coredump Writers +Custom coredumpers can define their own +.Dv coredump_writer +to pass to +.Fn sv_coredump . +.Pp +The +.Va ctx +member is opaque and only to be used by the coredumper itself. +.Pp +The +.Va init_fn +function, if it's provided, will be called by the +.Fn sv_coredump +implementation before any data is to be written. +This allows the writer implementation to record any coredump parameters that it +might need to capture, or setup the object to be written to. +.Pp +The +.Va write_fn +function will be called by the +.Fn sv_coredump +implementation to write out data. +The +.Va extend_fn +function will be called to enlarge the coredump, in the sense that a hole is +created in any difference between the current size and the new size. +For convenience, the +.Fn core_vn_write +and +.Fn core_vn_extend +functions used by the vnode coredumper are exposed in +.In sys/ucordumper.h , +and the +.Dv coredump_vnode_ctx +defined there should be populated with the vnode to write to. +.Sh SEE ALSO +.Xr setrlimit 2 , +.Xr core 5 +.Sh AUTHORS +This manual page was written by +.An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/share/man/man9/counter.9 b/share/man/man9/counter.9 index 1d3f3281ac0b..05af87e8263e 100644 --- a/share/man/man9/counter.9 +++ b/share/man/man9/counter.9 @@ -23,7 +23,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd March 11, 2021 +.Dd June 19, 2025 .Dt COUNTER 9 .Os .Sh NAME @@ -49,8 +49,14 @@ .Fn counter_u64_fetch "counter_u64_t c" .Ft void .Fn counter_u64_zero "counter_u64_t c" +.Ft struct counter_rate * +.Fn counter_rate_alloc "int flags" "int period" .Ft int64_t .Fn counter_ratecheck "struct counter_rate *cr" "int64_t limit" +.Ft uint64_t +.Fn counter_rate_get "struct counter_rate *cr" +.Ft void +.Fn counter_rate_free "struct counter_rate *cr" .Fn COUNTER_U64_SYSINIT "counter_u64_t c" .Fn COUNTER_U64_DEFINE_EARLY "counter_u64_t c" .In sys/sysctl.h @@ -133,6 +139,13 @@ value for any moment. Clear the counter .Fa c and set it to zero. +.It Fn counter_rate_alloc flags period +Allocate a new struct counter_rate. +.Fa flags +is passed to +.Xr malloc 9 . +.Fa period +is the time over which the rate is checked. .It Fn counter_ratecheck cr limit The function is a multiprocessor-friendly version of .Fn ppsratecheck @@ -140,11 +153,17 @@ which uses .Nm internally. Returns non-negative value if the rate is not yet reached during the current -second, and a negative value otherwise. -If the limit was reached on previous second, but was just reset back to zero, -then +period, and a negative value otherwise. +If the limit was reached during the previous period, but was just reset back +to zero, then .Fn counter_ratecheck returns number of events since previous reset. +.It Fn counter_rate_get cr +The number of hits to this check within the current period. +.It Fn counter_rate_free cr +Free the +.Fa cr +counter. .It Fn COUNTER_U64_SYSINIT c Define a .Xr SYSINIT 9 diff --git a/share/man/man9/cpu_machdep.9 b/share/man/man9/cpu_machdep.9 new file mode 100644 index 000000000000..415d86a8b766 --- /dev/null +++ b/share/man/man9/cpu_machdep.9 @@ -0,0 +1,425 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 (holder) +.\" +.\" This software was developed by SRI International, the University of +.\" Cambridge Computer Laboratory (Department of Computer Science and +.\" Technology), and Capabilities Limited under Defense Advanced Research +.\" Projects Agency (DARPA) Contract No. FA8750-24-C-B047 ("DEC"). +.\" +.Dd January 31, 2025 +.Dt cpu_machdep 9 +.Os +.Sh NAME +.Nm cpu_machdep , +.Nm cpu_copy_thread , +.Nm cpu_exec_vmspace_reuse , +.Nm cpu_exit , +.Nm cpu_fetch_syscall_args , +.Nm cpu_fork , +.Nm cpu_fork_kthread_handler , +.Nm cpu_idle , +.Nm cpu_idle_wakeup , +.Nm cpu_procctl , +.Nm cpu_set_syscall_retval , +.Nm cpu_set_upcall , +.Nm cpu_set_user_tls , +.Nm cpu_switch , +.Nm cpu_sync_core , +.Nm cpu_thread_alloc , +.Nm cpu_thread_clean , +.Nm cpu_thread_exit , +.Nm cpu_thread_free , +.Nm cpu_throw , +.Nm cpu_update_pcb +.Nd machine-dependent interfaces to handle CPU and thread state +.Sh SYNOPSIS +.In sys/proc.h +.In sys/ptrace.h +.Ft void +.Fn cpu_copy_thread "struct thread *td" "struct thread *td0" +.Ft bool +.Fn cpu_exec_vmspace_reuse "struct proc *p" "struct vm_map *map" +.Ft void +.Fn cpu_exit "struct thread *td" +.Ft int +.Fn cpu_fetch_syscall_args "struct thread *td" +.Ft void +.Fo cpu_fork +.Fa "struct thread *td1" "struct proc *p2" "struct thread *td2" "int flags" +.Fc +.Ft void +.Fo cpu_fork_kthread_handler +.Fa "struct thread *td" "void (*func)(void *)" "void *arg" +.Fc +.Ft void +.Fn cpu_idle "int busy" +.Ft int +.Fn cpu_idle_wakeup "int cpu" +.Ft int +.Fo cpu_procctl +.Fa "struct thread *td" "int idtype" "id_t id" "int com" "void *data" +.Fc +.Ft int +.Fn cpu_ptrace "struct thread *_td" "int req" "void *addr" "int data" +.Ft void +.Fn cpu_set_syscall_retval "struct thread *td" "int error" +.Ft int +.Fo cpu_set_upcall +.Fa "struct thread *td" "void (*entry)(void *)" "void *arg" "stack_t *stack" +.Fc +.Ft int +.Fn cpu_set_user_tls "struct thread *td" "void *tls_base" "int thr_flags" +.Ft void +.Fn cpu_switch "struct thread *old" "struct thread *new" "struct mtx *mtx" +.Ft void +.Fn cpu_sync_core "void" +.Ft void +.Fn cpu_thread_alloc "struct thread *td" +.Ft void +.Fn cpu_thread_clean "struct thread *td" +.Ft void +.Fn cpu_thread_exit "struct thread *td" +.Ft void +.Fn cpu_thread_free "struct thread *td" +.Ft void +.Fn cpu_throw "struct thread *old" "struct thread *new" +.Ft void +.Fn cpu_update_pcb "struct thread *td" +.Sh DESCRIPTION +These functions provide architecture-specific implementations of +machine-independent abstractions. +.Pp +.Fn cpu_exec_vmspace_reuse +returns true if +.Fn exec_new_vmspace +can reuse an existing +.Vt struct vmspace +.Pq Fa map +for the process +.Fa p +during +.Xr execve 2 . +This is only invoked if +.Fa map +is not shared with any other consumers. +If this returns false, +.Fn exec_new_vmspace +will create a new +.Vt struct vmspace . +.Pp +.Fn cpu_exit +releases machine-dependent resources other than the address space for the +process containing +.Fa td +during process exit. +.Pp +.Fn cpu_fork +copies and updates machine-dependent state +(for example, the pcb and user registers) from the forking thread +.Fa td1 +in an existing process to the new thread +.Fa td2 +in the new process +.Fa p2 . +This function must set up the new thread's kernel stack and pcb so that +.Fa td2 +calls +.Fn fork_exit +when it begins execution passing a pointer to +.Fn fork_return +as the +.Fa callout +argument and +.Fa td2 +as the +.Fa arg +argument. +.Pp +.Fn cpu_fork_kthread_handler +adjusts a new thread's initial pcb and/or kernel stack to pass +.Fa func +and +.Fa arg +as the +.Fa callout +and +.Fa arg +arguments to +.Fn fork_exit . +This must be called before a new thread is scheduled to run and is +used to set the +.Dq main +function for kernel threads. +.Pp +.Fn cpu_copy_thread +copies machine-dependent state (for example, the pcb and user registers) from +.Fa td +to +.Fa td0 +when creating a new thread in the same process. +This function must set up the new thread's kernel stack and pcb so that +.Fa td0 +calls +.Fn fork_exit +when it begins execution passing a pointer to +.Fn fork_return +as the +.Fa callout +argument and +.Fa td0 +as the +.Fa arg +argument. +.Pp +.Fn cpu_set_upcall +updates a new thread's initial user register state to call +.Fa entry +with +.Fa arg +as the sole argument using the user stack described in +.Fa stack . +.Pp +.Fn cpu_set_user_tls +sets a new thread's initial user thread pointer register to +reference the user TLS base pointer +.Fa tls_base . +The +.Fa thr_flags +argument provides flags bits, from the same namespace as +.Va flags +member of the +.Vt struct thr_param +argument to the +.Xr thr_new 2 +syscall. +.Pp +.Fn cpu_update_pcb +updates the pcb of the current thread with current user register values. +This is invoked before writing out register notes in a core dump. +This function typically only has to update user registers for the current +thread that are saved in the pcb during context switches rather than +in the trapframe on kernel entry. +.Pp +Note that when +.Fn cpu_update_pcb +is used, +threads in a process other than the current thread are stopped, +typically by +.Fn thread_single . +The pcbs of those stopped threads should already be updated by +.Fn cpu_switch . +.Pp +.Fn cpu_fetch_syscall_args +fetches the current system call arguments for the native FreeBSD ABI from the +current thread's user register state and/or user stack. +The arguments are saved in the +.Fa td_sa +member of +.Fa td . +.Pp +.Fn cpu_set_syscall_retval +updates the user register state for +.Fa td +to store system call error and return values. +If +.Fa error +is 0, +indicate success and return the two values in +.Fa td_retval . +If +.Fa error +is +.Dv ERESTART, +adjust the user PC to re-invoke the current system call after returning +to user mode. +If +.Fa error +is +.Dv EJUSTRETURN , +leave the current user register state unchanged. +For any other value of +.Fa error , +indicate error and return +.Fa error +as the error code. +.Pp +.Fn cpu_idle +waits for the next interrupt to occur on the current CPU. +If an architecture supports low power idling, +this function should place the CPU into a low power state while waiting. +.Fa busy +is a hint from the scheduler. +If +.Fa busy +is non-zero, +the scheduler expects a short sleep, +so the CPU should prefer low-latency over maximum power savings. +If +.Fa busy +is zero, +the CPU should maximumize power savings including deferring unnecessary +clock interrupts via +.Fn cpu_idleclock . +.Pp +.Fn cpu_idle_wakeup +awakens the idle CPU with the ID +.Fa cpu +from a low-power state. +.Pp +.Fn cpu_procctl +handles any machine-dependent +.Xr procctl 2 +requests. +.Pp +.Fn cpu_ptrace +handles any machine-dependent +.Xr ptrace 2 +requests. +.Pp +.Fn cpu_switch +switches the current CPU between threads by swapping register state. +This function saves the current CPU register state in the pcb of +.Fa old +and loads register values from the pcb of +.Fa new +before returning. +While the pcb generally contains caller-save kernel register state, +it can also contain user registers that are not saved in the trapframe. +.Pp +After saving the current CPU register state of +.Fa old , +.Fn cpu_switch +stores +.Fa mtx +in the +.Fa td_lock +member of +.Fa old +transferring ownership of the old thread. +No data belonging to +.Fa old +can be accessed after that store. +Specifically, the old thread's kernel stack must not be accessed after +this point. +.Pp +When +.Dv SCHED_ULE +is being used, +this function must wait (via spinning) for the +.Fa td_lock +member of +.Fa new +to change to a value not equal to +.Va &blocked_lock +before loading register values from +.Fa new +or accessing its kernel stack. +.Pp +From the caller's perspective, +.Fn cpu_switch +returns when +.Fa old +is rescheduled in the future, +possibly on a different CPU. +However, the implementation of +.Fn cpu_switch +returns immediately on the same CPU into the previously-saved context of +.Fa new . +.Pp +.Fn cpu_throw +is similar to +.Fn cpu_switch +but does not save any state for +.Fa old +or write to the old thread's +.Fa td_lock +member. +.Pp +.Fn cpu_sync_core +ensures that all possible speculation and out-of-order execution is +serialized on the current CPU. +Note that this is called from an IPI handler so only has to handle +additional serialization beyond that provided by handling an IPI. +.Ss Thread Object Lifecycle +These functions support the management of machine-dependent thread +state in conjunction with a thread object's lifecycle. +.Pp +The general model is that a thread object is allocated each time a +new kernel thread is created either by system calls like +.Xr fork 2 +or +.Xr thr_new 2 +or when kernel-only threads are created via +.Xr kproc_create 9 , +.Xr kproc_kthread_add 9 , +or +.Xr kthread_add 9 . +When a kernel thread exits, +the thread object is freed. +However, there is one special case to support an optimization where each +free process object caches a thread object. +When a process exits, the last thread object is not freed but remains +attached to the process. +When the process object is later reused for a new process in +.Xr fork 2 , +the kernel recycles that last thread object and uses it as the initial +thread in the new process. +When a thread is recycled, some of the steps in the thread allocation +and free cycle are skipped as an optimization. +.Pp +.Fn cpu_thread_alloc +initializes machine-dependent fields in +.Fa td +after allocating a new kernel stack. +This function typically sets the +.Fa td_pcb +and initial +.Fa td_frame +pointers. +.Fn cpu_thread_alloc +is called both when allocating a new thread object and +when a recycled thread allocates a new kernel stack. +Note that this function is +.Em not +called if a recycled thread reuses its existing kernel stack. +.Pp +.Fn cpu_thread_clean +releases any machine-dependent resources for the last thread in a +process during +.Xr wait 2 . +The thread is a candidate for recycling so should be reset to run as a +new thread in case it is recycled by a future +.Xr fork 2 . +.Pp +.Fn cpu_thread_exit +cleans any machine-dependent state in +.Fa td +while it is exiting. +This is called by the exiting thread so cannot free state needed during +in-kernel execution. +.Pp +.Fn cpu_thread_free +releases any machine-dependent state in +.Fa td +when it is being freed. +This is called for any thread that was not the last thread in a process +once it has finished execution. +.Sh SEE ALSO +.Xr fork 2 , +.Xr procctl 2 , +.Xr ptrace 2 , +.Xr thr_new 2 , +.Xr wait 2 , +.Xr kproc_create 9 , +.Xr kproc_kthread_add 9 , +.Xr kthread_add 9 , +.Xr mi_switch 9 +.Sh AUTHORS +This manual page was +developed by SRI International, the University of Cambridge Computer +Laboratory (Department of Computer Science and Technology), and +Capabilities Limited under contract +.Pq FA8750-24-C-B047 +.Pq Do DEC Dc . diff --git a/share/man/man9/cr_bsd_visible.9 b/share/man/man9/cr_bsd_visible.9 index f2d42f3835dc..d16f4bb6dd8f 100644 --- a/share/man/man9/cr_bsd_visible.9 +++ b/share/man/man9/cr_bsd_visible.9 @@ -107,11 +107,11 @@ and are not in the same jail. .El .Sh SEE ALSO -.Xr cr_canseeotheruids 9 , -.Xr cr_canseeothergids 9 , +.Xr cr_cansee 9 , .Xr cr_canseejailproc 9 , -.Xr priv_check_cred 9 , -.Xr cr_cansee 9 +.Xr cr_canseeothergids 9 , +.Xr cr_canseeotheruids 9 , +.Xr priv_check_cred 9 .Sh AUTHORS This function and its manual page were written by .An Olivier Certner Aq Mt olce.freebsd@certner.fr . diff --git a/share/man/man9/cr_cansee.9 b/share/man/man9/cr_cansee.9 index d5cdfdd6f8e5..a93afb8e5c89 100644 --- a/share/man/man9/cr_cansee.9 +++ b/share/man/man9/cr_cansee.9 @@ -77,7 +77,7 @@ The MAC subsystem denied visibility. denied visibility according to the BSD security policies in force. .El .Sh SEE ALSO -.Xr prison_check 9 , -.Xr mac 9 , .Xr cr_bsd_visible 9 , -.Xr p_cansee 9 +.Xr mac 9 , +.Xr p_cansee 9 , +.Xr prison_check 9 diff --git a/share/man/man9/cr_canseeothergids.9 b/share/man/man9/cr_canseeothergids.9 index 109d41a8545d..530335d5d5f7 100644 --- a/share/man/man9/cr_canseeothergids.9 +++ b/share/man/man9/cr_canseeothergids.9 @@ -79,5 +79,5 @@ Otherwise, it returns .Er ESRCH . .Sh SEE ALSO .Xr cr_bsd_visible 9 , -.Xr realgroupmember 9 , -.Xr priv_check_cred 9 +.Xr priv_check_cred 9 , +.Xr realgroupmember 9 diff --git a/share/man/man9/crypto_request.9 b/share/man/man9/crypto_request.9 index 45c3b62eea26..af62b9089561 100644 --- a/share/man/man9/crypto_request.9 +++ b/share/man/man9/crypto_request.9 @@ -28,7 +28,7 @@ .\" .\" * Other names and brands may be claimed as the property of others. .\" -.Dd November 2, 2022 +.Dd May 8, 2025 .Dt CRYPTO_REQUEST 9 .Os .Sh NAME @@ -466,17 +466,6 @@ Set by drivers prior to completing a request via .Fn crypto_done . .It Fa crp_flags A bitmask of flags. -The following flags are available in addition to flags discussed previously: -.Bl -tag -width CRYPTO_F_DONE -.It Dv CRYPTO_F_DONE -Set by -.Fa crypto_done -before calling -.Fa crp_callback . -This flag is not very useful and will likely be removed in the future. -It can only be safely checked from the callback routine at which point -it is always set. -.El .It Fa crp_cipher_key Pointer to a request-specific encryption key. If this value is not set, diff --git a/share/man/man9/dev_clone.9 b/share/man/man9/dev_clone.9 index f5f59e3c6666..56bdd1a9a248 100644 --- a/share/man/man9/dev_clone.9 +++ b/share/man/man9/dev_clone.9 @@ -42,7 +42,7 @@ EVENTHANDLER_REGISTER(dev_clone, clone_handler, arg, priority); .Sh DESCRIPTION A device driver may register a listener that will be notified each time a name lookup on the -.Xr devfs 5 +.Xr devfs 4 mount point fails to find the vnode. A listener shall be registered for the .Va dev_clone @@ -72,5 +72,5 @@ that were started before .Fn drain_dev_clone_events call, are finished before it returns control. .Sh SEE ALSO -.Xr devfs 5 , +.Xr devfs 4 , .Xr namei 9 diff --git a/share/man/man9/dev_refthread.9 b/share/man/man9/dev_refthread.9 index e12b5f49a0e5..f615725b0a47 100644 --- a/share/man/man9/dev_refthread.9 +++ b/share/man/man9/dev_refthread.9 @@ -47,7 +47,7 @@ The and .Fn dev_relthread routines provide a safe way to access -.Xr devfs 5 +.Xr devfs 4 devices that may be concurrently destroyed by .Fn destroy_dev (e.g., removable media). @@ -143,7 +143,7 @@ and do not initialize the value pointed to by the parameter in any way. .Ef .Sh SEE ALSO -.Xr devfs 5 , +.Xr devfs 4 , .Xr destroy_dev 9 .Sh CAVEATS Do not invoke diff --git a/share/man/man9/devclass.9 b/share/man/man9/devclass.9 index d3c83133ae17..cbf81f3b0fa3 100644 --- a/share/man/man9/devclass.9 +++ b/share/man/man9/devclass.9 @@ -46,10 +46,11 @@ Each has a name and there cannot be two devclasses with the same name. This ensures that unique unit numbers are allocated to device instances. +All instances with the same name are treated as being the same. .Pp -Beware that this means -.Vt devclass -must be the same for different bus attachments of the same device driver. +When no specific unit number is needed, +.Vt DEVICE_UNIT_ANY +is used. .Sh SEE ALSO .Xr devclass_add_driver 9 , .Xr devclass_delete_driver 9 , diff --git a/share/man/man9/devfs_set_cdevpriv.9 b/share/man/man9/devfs_set_cdevpriv.9 index 3258ca082e5f..0cbfd3eebeb7 100644 --- a/share/man/man9/devfs_set_cdevpriv.9 +++ b/share/man/man9/devfs_set_cdevpriv.9 @@ -62,7 +62,7 @@ Currently, functioning of these functions is restricted to the context of the .Fa cdevsw switch method calls performed as -.Xr devfs 5 +.Xr devfs 4 operations in response to system calls that use filedescriptors. .Pp The @@ -151,7 +151,7 @@ any blockable locking inside the callback .Sh SEE ALSO .Xr close 2 , .Xr open 2 , -.Xr devfs 5 +.Xr devfs 4 .Sh HISTORY The .Fn devfs_cdevpriv diff --git a/share/man/man9/device_add_child.9 b/share/man/man9/device_add_child.9 index 423869d6ff6b..dfd0d19049bc 100644 --- a/share/man/man9/device_add_child.9 +++ b/share/man/man9/device_add_child.9 @@ -51,7 +51,7 @@ arguments specify the name and unit number of the device. If the name is unknown then the caller should pass .Dv NULL . If the unit is unknown then the caller should pass -.Dv -1 +.Dv DEVICE_UNIT_ANY and the system will choose the next available unit number. .Pp The name of the device is used to determine which drivers might be @@ -70,7 +70,7 @@ be specified as the device name. .Pp Normally unit numbers will be chosen automatically by the system and a unit number of -.Dv -1 +.Dv DEVICE_UNIT_ANY should be given. When a specific unit number is desired (e.g.,\& for wiring a particular piece of hardware to a pre-configured unit number), that unit should diff --git a/share/man/man9/device_delete_child.9 b/share/man/man9/device_delete_child.9 index f6c08cb52e16..819c7f5e36b9 100644 --- a/share/man/man9/device_delete_child.9 +++ b/share/man/man9/device_delete_child.9 @@ -26,7 +26,7 @@ .\" (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 June 16, 1998 +.Dd February 5, 2025 .Dt DEVICE_DELETE_CHILD 9 .Os .Sh NAME @@ -41,13 +41,26 @@ The specified device is removed from .Fa dev and deleted. -If the device is currently attached, it is first detached (see -.Xr DEVICE_ATTACH 9 -and -.Xr DEVICE_DETACH 9 ) . +If the device is currently attached, it is first detached via +.Xr device_detach 9 . +If +.Fn device_detach +fails, +its error value is returned. +Otherwise, +all descendant devices of +.Fa child +are deleted and zero is returned. +.Pp +The +.Xr BUS_CHILD_DELETED 9 +method is invoked for each device that is deleted. +This permits the parent device's driver to tear down any state associated +with child devices such as ivars. .Sh RETURN VALUES Zero is returned on success, otherwise an error is returned. .Sh SEE ALSO +.Xr BUS_CHILD_DELETED 9 , .Xr device_add_child 9 .Sh AUTHORS This manual page was written by diff --git a/share/man/man9/device_probe_and_attach.9 b/share/man/man9/device_probe_and_attach.9 index 5d5de52cee66..0c438be3a483 100644 --- a/share/man/man9/device_probe_and_attach.9 +++ b/share/man/man9/device_probe_and_attach.9 @@ -26,33 +26,139 @@ .\" (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 June 16, 1998 +.Dd February 5, 2025 .Dt DEVICE_PROBE_AND_ATTACH 9 .Os .Sh NAME +.Nm device_attach , +.Nm device_detach , +.Nm device_probe , .Nm device_probe_and_attach -.Nd initialise a device +.Nd manage device's connection to a device driver .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft int +.Fn device_attach "device_t dev" +.Ft int +.Fn device_detach "device_t dev" +.Ft int +.Fn device_probe "device_t dev" +.Ft int .Fn device_probe_and_attach "device_t dev" .Sh DESCRIPTION -This function is called during autoconfiguration to initialise the -devices in the system. -For each device, the +These functions manage the relationship between a device and device drivers. +.Pp +.Fn device_probe +invokes the .Xr DEVICE_PROBE 9 -method of each suitable driver is called and if a probe succeeds, a -description of the device is printed and the +method of each suitable driver and to find the driver with the best match for +.Fa dev . +If a matching driver is found, +.Fa dev +is set to the +.Dv DS_ALIVE +state and zero is returned. +If +.Fa dev +is already attached to a device driver or has been disabled via +.Xr device_disable 9 , +then it will not be probed and -1 is returned. +.Pp +.Fn device_attach +fully attaches a device driver to +.Fa dev . +This function prints a description of the device and invokes the +.Xr DEVICE_ATTACH 9 +method. +If the +.Xr DEVICE_ATTACH 9 +method succeeds, +.Fa dev +is set to the +.Dv DS_ATTACHED +state and zero is returned. +If the .Xr DEVICE_ATTACH 9 -method is called. -If the device is disabled using -.Xr device_disable 9 -then it will not be probed. +method fails, +.Xr BUS_CHILD_DETACHED 9 +is called and an error value is returned. +.Pp +If the device name and unit are disabled by a hint, +.Fn device_attach +disables the device, demotes it to the +.Dv DS_NOTPRESENT +state, +and returns +.Dv ENXIO . +The device retains its device name and unit and can be re-enabled via +.Xr devctl 8 . +.Pp +.Fn device_probe_and_attach +is a wrapper function around +.Fn device_probe +and +.Fn device_attach +that fully initialises a device. +If +.Fa dev +is already attached or disabled, +.Fn device_probe_and_attach +leaves the device unchanged and returns zero. +Otherwise, +.Fn device_probe +is used to identify a device driver for +.Fa dev +and +.Fn device_attach +finalizes attaching the driver to +.Fa dev . +Device drivers should generally use this function to initialize a device +rather than direct calls to +.Fn device_probe +and +.Fn device_attach . +.Pp +.Fn device_detach +detaches the device driver from +.Fa dev . +This function invokes the +.Xr DEVICE_DETACH 9 +method to tear down device driver state for +.Fa dev . +If the method fails, +its error value is returned and +.Fa dev +remains attached. +If the method succeeds, +otherwise, +.Xr BUS_CHILD_DETACHED 9 +is called, +the device is set to the +.Dv DS_NOTPRESENT +state, +and zero is returned. +If a device is busy, +.Fn device_detach +fails with +.Dv EBUSY +and leaving +.Fa dev +unchanged. .Sh RETURN VALUES Zero is returned on success, otherwise an appropriate error is returned. +In addition, +.Fn device_probe +returns -1 if +.Fa dev +is disabled or already attached. .Sh SEE ALSO +.Xr devctl 8 , +.Xr BUS_CHILD_DETACHED 9 , .Xr device 9 , +.Xr DEVICE_ATTACH 9 , +.Xr DEVICE_DETACH 9 , +.Xr DEVICE_PROBE 9 , .Xr driver 9 .Sh AUTHORS This manual page was written by diff --git a/share/man/man9/disk.9 b/share/man/man9/disk.9 index 047abb96c619..41436427cbc2 100644 --- a/share/man/man9/disk.9 +++ b/share/man/man9/disk.9 @@ -51,7 +51,7 @@ disk-like storage devices to advertise the device to other kernel components, including .Xr GEOM 4 and -.Xr devfs 5 . +.Xr devfs 4 . .Pp Each disk device is described by a .Vt "struct disk" @@ -242,8 +242,8 @@ Typically used to store a pointer to the drivers structure for this disk device. .El .Sh SEE ALSO -.Xr GEOM 4 , -.Xr devfs 5 +.Xr devfs 4 , +.Xr GEOM 4 .Sh HISTORY The .Nm kernel disk storage API diff --git a/share/man/man9/dnv.9 b/share/man/man9/dnv.9 index 8c89d6599801..16f603df8392 100644 --- a/share/man/man9/dnv.9 +++ b/share/man/man9/dnv.9 @@ -23,13 +23,13 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd July 26, 2016 +.Dd January 3, 2025 .Dt DNV 9 .Os .Sh NAME .Nm dnvlist_get , .Nm dnvlist_take -.Nd "API for getting name/value pairs. Nonexistent pairs do not raise an error." +.Nd "API for getting name/value pairs with a default value" .Sh LIBRARY .Lb libnv .Sh SYNOPSIS @@ -63,26 +63,32 @@ The .Nm libnv library permits easy management of name/value pairs and can send and receive them over sockets. -For more information, also see +For more information, see .Xr nv 9 . .Pp The .Nm dnvlist_get -family of functions returns the value associated with the specified name. -If an element of the specified name does not exist, the function returns the +functions return the value associated with +.Fa name . +If an element named +.Fa name +does not exist, the function returns the value provided in .Fa defval . Returned strings, nvlists, descriptors, binaries, or arrays must not be modified -by the user. -They still belong to the nvlist. +by the user since they still belong to the nvlist. If the nvlist is in an error state, attempts to use any of these functions will cause the program to abort. .Pp The .Nm dnvlist_take -family of functions returns the value associated with the specified name and -removes the element from the nvlist. -If an element of the supplied name does not exist, the value provided in +functions return the value associated with +.Fa name +and removes the associated element from +.Fa nvl . +If an element named +.Fa name +does not exist, the value provided in .Nm defval is returned. When the value is a string, binary, or array value, the caller is diff --git a/share/man/man9/domain.9 b/share/man/man9/domain.9 index eaa279cef996..dab8cff89e12 100644 --- a/share/man/man9/domain.9 +++ b/share/man/man9/domain.9 @@ -183,7 +183,6 @@ has an empty slot in its .Va dom_protosw . Dynamically added protocol can later be unloaded with .Fn protosw_unregister . -.Ed .Sh RETURN VALUES The .Fn domain_add diff --git a/share/man/man9/domainset.9 b/share/man/man9/domainset.9 index 816ce29f04f7..702c9f83a88b 100644 --- a/share/man/man9/domainset.9 +++ b/share/man/man9/domainset.9 @@ -22,7 +22,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd April 14, 2021 +.Dd June 24, 2025 .Dt DOMAINSET 9 .Os .Sh NAME @@ -54,6 +54,8 @@ struct domainset { .Ft struct domainset * .Fn domainset_create "const struct domainset *key" .Ft int +.Fn domainset_populate "struct domainset *domain" "domainset_t *mask" "int policy" "size_t mask_size" +.Ft int .Fn sysctl_handle_domainset "SYSCTL_HANDLER_ARGS" .Sh DESCRIPTION The @@ -137,6 +139,7 @@ These policies should be used in preference to to avoid blocking indefinitely on a .Dv M_WAITOK request. +.Pp The .Fn domainset_create function takes a partially filled in domainset as a key and returns a @@ -148,6 +151,17 @@ is an immutable type that is shared among all matching keys and must not be modified after return. .Pp The +.Fn domainset_populate +function fills a +.Vt domainset +struct using a domain mask and policy. +It is used for validating and +translating a domain mask and policy into a +.Vt domainset +struct when creating a custom domainset using +.Vt domainset_create . +.Pp +The .Fn sysctl_handle_domainset function is provided as a convenience for modifying or viewing domainsets that are not accessible via diff --git a/share/man/man9/firmware.9 b/share/man/man9/firmware.9 index 883f0a2634d4..43f965a20fb7 100644 --- a/share/man/man9/firmware.9 +++ b/share/man/man9/firmware.9 @@ -201,7 +201,7 @@ whether compiled in, or preloaded by or manually loaded with .Xr kldload 8 . However, a system can implement additional mechanisms to bring -these images in memory before calling +these images into memory before calling .Fn firmware_register . .Pp When @@ -341,13 +341,13 @@ uses the following algorithm to find firmware images: .It If an existing firmware image is registered for .Fa imagename, -.that image is returned. +that image is returned. .It If .Fa imagename matches the trailing subpath of a registered image with a full path, that image is returned. .It -he kernel linker searches for a kernel module named +The kernel linker searches for a kernel module named .Fa imagename . If a kernel module is found, it is loaded, and the list of registered firmware images is searched again. diff --git a/share/man/man9/g_provider.9 b/share/man/man9/g_provider.9 index d421af3b1264..940772b26fa5 100644 --- a/share/man/man9/g_provider.9 +++ b/share/man/man9/g_provider.9 @@ -50,7 +50,7 @@ The function creates a new provider on given geom .Fa gp . The name of the provider, which will appear as device in -.Xr devfs 5 , +.Xr devfs 4 , is created in a .Xr printf 3 Ns diff --git a/share/man/man9/groupmember.9 b/share/man/man9/groupmember.9 index b7865a35fdc9..e7e28bae3ac9 100644 --- a/share/man/man9/groupmember.9 +++ b/share/man/man9/groupmember.9 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" -.Dd August 18, 2023 +.Dd October 31, 2024 .Dt GROUPMEMBER 9 .Os .Sh NAME @@ -35,9 +35,9 @@ .In sys/param.h .In sys/ucred.h .Ft bool -.Fn groupmember "gid_t gid" "struct ucred *cred" +.Fn groupmember "gid_t gid" "const struct ucred *cred" .Ft bool -.Fn realgroupmember "gid_t gid" "struct ucred *cred" +.Fn realgroupmember "gid_t gid" "const struct ucred *cred" .Sh DESCRIPTION The .Fn groupmember @@ -69,7 +69,7 @@ or .Dv false otherwise. .Sh SEE ALSO -.Xr getgroups 2 +.Xr getgroups 2 , .Xr setgroups 2 .Sh AUTHORS This manual page was initially written by diff --git a/share/man/man9/ieee80211.9 b/share/man/man9/ieee80211.9 index 100b4e7540a5..40c8c243a77c 100644 --- a/share/man/man9/ieee80211.9 +++ b/share/man/man9/ieee80211.9 @@ -25,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd January 26, 2021 +.Dd April 24, 2024 .Dt IEEE80211 9 .Os .Sh NAME @@ -514,6 +514,8 @@ General capabilities are specified by .Vt ic_caps . Hardware cryptographic capabilities are specified by .Vt ic_cryptocaps . +Software cryptographic capabilities are specified by +.Vt ic_sw_cryptocaps . 802.11n capabilities, if any, are specified by .Vt ic_htcaps . The diff --git a/share/man/man9/ifnet.9 b/share/man/man9/ifnet.9 index b835c51c546f..3c45e4f29e2d 100644 --- a/share/man/man9/ifnet.9 +++ b/share/man/man9/ifnet.9 @@ -26,10 +26,11 @@ .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd May 24, 2022 +.Dd December 10, 2024 .Dt IFNET 9 .Os .Sh NAME +.Nm if_t , .Nm ifnet , .Nm ifaddr , .Nm ifqueue , @@ -44,46 +45,44 @@ .In net/if_types.h .\" .Ss "Interface Manipulation Functions" -.Ft "struct ifnet *" +.Ft "if_t" .Fn if_alloc "u_char type" -.Ft "struct ifnet *" +.Ft "if_t" .Fn if_alloc_dev "u_char type" "device_t dev" -.Ft "struct ifnet *" +.Ft "if_t" .Fn if_alloc_domain "u_char type" "int numa_domain" .Ft void -.Fn if_attach "struct ifnet *ifp" +.Fn if_attach "if_t ifp" .Ft void -.Fn if_detach "struct ifnet *ifp" +.Fn if_detach "if_t ifp" .Ft void -.Fn if_free "struct ifnet *ifp" +.Fn if_free "if_t ifp" .Ft void -.Fn if_free_type "struct ifnet *ifp" "u_char type" +.Fn if_free_type "if_t ifp" "u_char type" .Ft void -.Fn if_down "struct ifnet *ifp" +.Fn if_down "if_t ifp" .Ft int .Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct thread *td" .Ft int -.Fn ifpromisc "struct ifnet *ifp" "int pswitch" +.Fn ifpromisc "if_t ifp" "int pswitch" .Ft int -.Fn if_allmulti "struct ifnet *ifp" "int amswitch" -.Ft "struct ifnet *" +.Fn if_allmulti "if_t ifp" "int amswitch" +.Ft "if_t" .Fn ifunit "const char *name" -.Ft "struct ifnet *" +.Ft "if_t" .Fn ifunit_ref "const char *name" .Ft void -.Fn if_up "struct ifnet *ifp" +.Fn if_up "if_t ifp" .\" .Ss "Interface Address Functions" .Ft "struct ifaddr *" -.Fn ifaddr_byindex "u_short idx" -.Ft "struct ifaddr *" .Fn ifa_ifwithaddr "struct sockaddr *addr" .Ft "struct ifaddr *" .Fn ifa_ifwithdstaddr "struct sockaddr *addr" "int fib" .Ft "struct ifaddr *" .Fn ifa_ifwithnet "struct sockaddr *addr" "int ignore_ptp" "int fib" .Ft "struct ifaddr *" -.Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp" +.Fn ifaof_ifpforaddr "struct sockaddr *addr" "if_t ifp" .Ft void .Fn ifa_ref "struct ifaddr *ifa" .Ft void @@ -91,35 +90,221 @@ .\" .Ss "Interface Multicast Address Functions" .Ft int -.Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" +.Fn if_addmulti "if_t ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" .Ft int -.Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa" +.Fn if_delmulti "if_t ifp" "struct sockaddr *sa" .Ft "struct ifmultiaddr *" -.Fn if_findmulti "struct ifnet *ifp" "struct sockaddr *sa" +.Fn if_findmulti "if_t ifp" "struct sockaddr *sa" +.Ss "Output queue accessors" +.Fn if_dequeue "if_t ifp" "struct mbuf *m" .Ss "Output queue macros" .Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m" .\" +.Ss "if_t accesors" +.Ft uint64_t +.Fn if_setbaudrate "if_t ifp" "uint64_t baudrate" +.Ft uint64_t +.Fn if_getbaudrate "const if_t ifp" +.Ft int +.Fn if_setcapabilities "if_t ifp" "int capabilities" +.Ft int +.Fn if_setcapabilitiesbit "if_t ifp" "int setbit" "int clearbit" +.Ft int +.Fn if_getcapabilities "const if_t ifp" +.Ft int +.Fn if_togglecapenable "if_t ifp" "int togglecap" +.Ft int +.Fn if_setcapenable "if_t ifp" "int capenable" +.Ft int +.Fn if_setcapenablebit "if_t ifp" "int setcap" "int clearcap" +.Ft int +.Fn if_getcapenable "const if_t ifp" +.Ft int +.Fn if_setcapabilities2 "if_t ifp" "int capabilities" +.Ft int +.Fn if_setcapabilities2bit "if_t ifp" "int setbit" "int clearbit" +.Ft int +.Fn if_getcapabilities2 "const if_t ifp" +.Ft int +.Fn if_togglecapenable2 "if_t ifp" "int togglecap" +.Ft int +.Fn if_setcapenable2 "if_t ifp" "int capenable" +.Ft int +.Fn if_setcapenable2bit "if_t ifp" "int setcap" "int clearcap" +.Ft int +.Fn if_getcapenable2 "const if_t ifp" +.Ft int +.Fn if_getdunit "const if_t ifp" +.Ft int +.Fn if_getindex "const if_t ifp" +.Ft int +.Fn if_getidxgen "const if_t ifp" +.Ft const char * +.Fn if_getdname "const if_t ifp" +.Ft void +.Fn if_setdname "if_t ifp" "const char *name" +.Ft const char * +.Fn if_name "if_t ifp" +.Ft int +.Fn if_setname "if_t ifp" "const char *name" +.Ft void +.Fn if_setdescr "if_t ifp" "char *descrbuf" +.Ft char * +.Fn if_allocdescr "size_t sz" "int malloc_flag" +.Ft void +.Fn if_freedescr "char *descrbuf" +.Ft int +.Fn if_getalloctype "const if_t ifp" +.Ft int +.Fn if_gettype "const if_t ifp" +.Ft int +.Fn if_setdev "if_t ifp" "void *dev" +.Ft int +.Fn if_setdrvflagbits "if_t ifp" "int if_setflags" "int clear_flags" +.Ft int +.Fn if_getdrvflags "const if_t ifp" +.Ft int +.Fn if_setdrvflags "if_t ifp" "int flags" +.Ft int +.Fn if_getlinkstate "if_t ifp" +.Ft int +.Fn if_clearhwassist "if_t ifp" +.Ft int +.Fn if_sethwassistbits "if_t ifp" "int toset" "int toclear" +.Ft int +.Fn if_sethwassist "if_t ifp" "int hwassist_bit" +.Ft int +.Fn if_gethwassist "const if_t ifp" +.Ft int +.Fn if_togglehwassist "if_t ifp" "int toggle_bits" +.Ft int +.Fn if_setsoftc "if_t ifp" "void *softc" +.Ft void * +.Fn if_getsoftc "if_t ifp" +.Ft void +.Fn if_setllsoftc "if_t ifp" "void *softc" +.Ft void * +.Fn if_getllsoftc "if_t ifp" +.Ft u_int +.Fn if_getfib "if_t ifp" +.Ft uint8_t +.Fn if_getaddrlen "if_t ifp" +.Ft int +.Fn if_gethwaddr "const if_t ifp" "struct ifreq *" +.Ft const uint8_t * +.Fn if_getbroadcastaddr "const if_t ifp" +.Ft void +.Fn if_setbroadcastaddr "if_t ifp" "const uint8_t *" +.Ft int +.Fn if_setmtu "if_t ifp" "int mtu" +.Ft int +.Fn if_getmtu "const if_t ifp" +.Ft int +.Fn if_getmtu_family "const if_t ifp" "int family" +.Ft void +.Fn if_notifymtu "if_t ifp" +.Ft int +.Fn if_setflagbits "if_t ifp" "int set" "int clear" +.Ft int +.Fn if_setflags "if_t ifp" "int flags" +.Ft int +.Fn if_getflags "const if_t ifp" +.Ft int +.Fn if_getnumadomain "if_t ifp" +.Ft int +.Fn if_sendq_empty "if_t ifp" +.Ft int +.Fn if_setsendqready "if_t ifp" +.Ft int +.Fn if_setsendqlen "if_t ifp" "int tx_desc_count" +.Ft int +.Fn if_sethwtsomax "if_t ifp" "u_int if_hw_tsomax" +.Ft int +.Fn if_sethwtsomaxsegcount "if_t ifp" "u_int if_hw_tsomaxsegcount" +.Ft int +.Fn if_sethwtsomaxsegsize "if_t ifp" "u_int if_hw_tsomaxsegsize" +.Ft u_int +.Fn if_gethwtsomax "const if_t ifp" +.Ft u_int +.Fn if_gethwtsomaxsegcount "const if_t ifp" +.Ft u_int +.Fn if_gethwtsomaxsegsize "const if_t ifp" +.Ft void +.Fn if_setnetmapadapter "if_t ifp" "struct netmap_adapter *na" +.Ft struct netmap_adapter * +.Fn if_getnetmapadapter "if_t ifp" +.Ft void +.Fn if_input "if_t ifp" "struct mbuf* sendmp" +.Ft int +.Fn if_sendq_prepend "if_t ifp" "struct mbuf *m" +.Ft struct mbuf * +.Fn if_dequeue "if_t ifp" +.Ft int +.Fn if_setifheaderlen "if_t ifp" "int len" +.Ft void +.Fn if_setrcvif "struct mbuf *m" "if_t ifp" +.Ft void +.Fn if_setvtag "struct mbuf *m" "u_int16_t tag" +.Ft u_int16_t +.Fn if_getvtag "struct mbuf *m" +.Ft int +.Fn if_vlantrunkinuse "if_t ifp" +.Ft caddr_t +.Fn if_getlladdr "const if_t ifp" +.Ft struct vnet * +.Fn if_getvnet "const if_t ifp" +.Ft void * +.Fn if_gethandle "u_char" +.Ft void +.Fn if_bpfmtap "if_t ifp" "struct mbuf *m" +.Ft void +.Fn if_etherbpfmtap "if_t ifp" "struct mbuf *m" +.Ft void +.Fn if_vlancap "if_t ifp" +.Ft int +.Fn if_transmit "if_t ifp" "struct mbuf *m" +.Ft void +.Fn if_init "if_t ifp" "void *ctx" +.Ft int +.Fn if_resolvemulti "if_t ifp" "struct sockaddr **" "struct sockaddr *" +.Ft uint64_t +.Fn if_getcounter "if_t ifp" "ift_counter counter" +.Ft struct label * +.Fn if_getmaclabel "if_t ifp" +.Ft void +.Fn if_setmaclabel "if_t ifp" "struct label *label" +.Ft struct bpf_if * +.Fn if_getbpf "if_t ifp" +.Ft uint8_t +.Fn if_getpcp "if_t ifp" +.Ft void * +.Fn if_getl2com "if_t ifp" +.Ft struct ifvlantrunk * +.Fn if_getvlantrunk "if_t ifp" +.Ft bool +.Fn if_altq_is_enabled "if_t ifp" +.\" .Ss "struct ifnet Member Functions" .Ft void -.Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m" +.Fn \*(lp*if_input\*(rp "if_t ifp" "struct mbuf *m" .Ft int .Fo \*(lp*if_output\*(rp -.Fa "struct ifnet *ifp" "struct mbuf *m" +.Fa "if_t ifp" "struct mbuf *m" .Fa "const struct sockaddr *dst" "struct route *ro" .Fc .Ft void -.Fn \*(lp*if_start\*(rp "struct ifnet *ifp" +.Fn \*(lp*if_start\*(rp "if_t ifp" .Ft int -.Fn \*(lp*if_transmit\*(rp "struct ifnet *ifp" "struct mbuf *m" +.Fn \*(lp*if_transmit\*(rp "if_t ifp" "struct mbuf *m" .Ft void -.Fn \*(lp*if_qflush\*(rp "struct ifnet *ifp" +.Fn \*(lp*if_qflush\*(rp "if_t ifp" .Ft int -.Fn \*(lp*if_ioctl\*(rp "struct ifnet *ifp" "u_long cmd" "caddr_t data" +.Fn \*(lp*if_ioctl\*(rp "if_t ifp" "u_long cmd" "caddr_t data" .Ft void .Fn \*(lp*if_init\*(rp "void *if_softc" .Ft int .Fo \*(lp*if_resolvemulti\*(rp -.Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr" +.Fa "if_t ifp" "struct sockaddr **retsa" "struct sockaddr *addr" .Fc .Ss "struct ifaddr member function" .Ft void @@ -196,8 +381,6 @@ address .Xr link_addr 3 ) describing the link layer implemented by the interface (if any) is accessed by the -.Fn ifaddr_byindex -function or .Va if_addr structure. (Some trivial interfaces do not provide any link layer addresses; @@ -216,232 +399,98 @@ Interfaces are also associated with an output queue, defined as a .Vt "struct ifqueue" ; this structure is used to hold packets while the interface is in the process of sending another. -.Ss The ifnet Structure -The fields of -.Vt "struct ifnet" +.Ss The ifnet accessors +The accessors for +.Vt "if_t" are as follows: -.Bl -tag -width ".Va if_capabilities" -offset indent -.It Va if_softc -.Pq Vt "void *" -A pointer to the driver's private state block. -(Initialized by driver.) -.It Va if_l2com -.Pq Vt "void *" -A pointer to the common data for the interface's layer 2 protocol. -(Initialized by -.Fn if_alloc . ) -.It Va if_vnet -.Pq Vt "struct vnet *" -A pointer to the virtual network stack instance. -(Initialized by -.Fn if_attach . ) -.It Va if_home_vnet -.Pq Vt "struct vnet *" -A pointer to the parent virtual network stack, where this -.Vt "struct ifnet" -originates from. -(Initialized by -.Fn if_attach . ) -.It Va if_link -.Pq Fn TAILQ_ENTRY ifnet -.Xr queue 3 -macro glue. -.It Va if_xname -.Pq Vt "char *" -The name of the interface, -(e.g., -.Dq Li fxp0 -or -.Dq Li lo0 ) . -(Initialized by driver -(usually via -.Fn if_initname ) . ) -.It Va if_dname -.Pq Vt "const char *" -The name of the driver. -(Initialized by driver -(usually via -.Fn if_initname ) . ) -.It Va if_dunit +.Bl -tag -width indent -offset indent +.It Fn if_getbaudrate Fn if_setbaudrate +.Pq Vt u_long +The line rate of the interface, in bits per second. +.It Fn if_setcapabilities Fn if_setcapabilitiesbit Fn if_getcapabilities +.Pq Vt int +Flags describing the capabilities the interface supports (see below). +.It Fn if_getcapenable Fn if_setcapenable Fn if_setcapenablebit Fn if_togglecapenable +.Pq Vt int +Flags describing the enabled capabilities of the interface (see below). +.It Fn if_getcapabilities2 Fn if_setcapabilities2 Fn if_setcapabilities2bit +.It Fn if_getcapenable2 Fn if_setcapenable2 Fn if_setcapenable2bit Fn if_togglecapenable2 +.It Fn if_getdunit .Pq Vt int A unique number assigned to each interface managed by a particular driver. Drivers may choose to set this to .Dv IF_DUNIT_NONE if a unit number is not associated with the device. -(Initialized by driver -(usually via -.Fn if_initname ) . ) -.It Va if_refcount -.Pq Vt u_int -The reference count. -(Initialized by -.Fn if_alloc . ) -.It Va if_addrhead -.Pq Vt "struct ifaddrhead" -The head of the -.Xr queue 3 -.Li TAILQ -containing the list of addresses assigned to this interface. -.It Va if_pcount -.Pq Vt int -A count of promiscuous listeners on this interface, used to -reference-count the -.Dv IFF_PROMISC -flag. -.It Va if_carp -.Pq Vt "struct carp_if *" -A pointer to the CARP interface structure, -.Xr carp 4 . -(Initialized by the driver-specific -.Fn if_ioctl -routine.) -.It Va if_bpf -.Pq Vt "struct bpf_if *" -Opaque per-interface data for the packet filter, -.Xr bpf 4 . -(Initialized by -.Fn bpf_attach . ) -.It Va if_index +(Initialized by driver, usually via +.Fn if_initname . ) +.It Fn if_getindex .Pq Vt u_short -A unique number assigned to each interface in sequence as it is -attached. +Return the unique number assigned to the device when attached. This number can be used in a .Vt "struct sockaddr_dl" to refer to a particular interface by index (see .Xr link_addr 3 ) . -(Initialized by -.Fn if_alloc . ) -.It Va if_vlantrunk -.Pq Vt struct ifvlantrunk * -A pointer to 802.1Q trunk structure, -.Xr vlan 4 . -(Initialized by the driver-specific -.Fn if_ioctl -routine.) -.It Va if_flags -.Pq Vt int -Flags describing operational parameters of this interface (see below). -(Manipulated by generic code.) -.It Va if_drv_flags -.Pq Vt int -Flags describing operational status of this interface (see below). -(Manipulated by driver.) -.It Va if_capabilities -.Pq Vt int -Flags describing the capabilities the interface supports (see below). -.It Va if_capenable -.Pq Vt int -Flags describing the enabled capabilities of the interface (see below). -.It Va if_linkmib -.Pq Vt "void *" -A pointer to an interface-specific MIB structure exported by -.Xr ifmib 4 . -(Initialized by driver.) -.It Va if_linkmiblen -.Pq Vt size_t -The size of said structure. -(Initialized by driver.) -.It Va if_data -.Pq Vt "struct if_data" -More statistics and information; see -.Sx "The if_data structure" , -below. -(Initialized by driver, manipulated by both driver and generic -code.) -.It Va if_multiaddrs -.Pq Vt struct ifmultihead -The head of the -.Xr queue 3 -.Li TAILQ -containing the list of multicast addresses assigned to this interface. -.It Va if_amcount -.Pq Vt int -A number of multicast requests on this interface, used to -reference-count the -.Dv IFF_ALLMULTI -flag. -.It Va if_addr -.Pq Vt "struct ifaddr *" -A pointer to the link-level interface address. -(Initialized by -.Fn if_alloc . ) -.\" .It Va if_llsoftc -.\" .Pq Vt "void *" -.\" The purpose of the field is unclear. -.It Va if_snd -.Pq Vt "struct ifaltq" -The output queue. -(Manipulated by driver.) -.It Va if_broadcastaddr -.Pq Vt "const u_int8_t *" -A link-level broadcast bytestring for protocols with variable address -length. -.It Va if_bridge -.Pq Vt "void *" -A pointer to the bridge interface structure, -.Xr if_bridge 4 . -(Initialized by the driver-specific -.Fn if_ioctl -routine.) -.It Va if_label -.Pq Vt "struct label *" -A pointer to the MAC Framework label structure, -.Xr mac 4 . -(Initialized by -.Fn if_alloc . ) -.It Va if_afdata -.Pq Vt "void *" -An address family dependent data region. -.It Va if_afdata_initialized -.Pq Vt int -Used to track the current state of address family initialization. -.It Va if_afdata_lock -.Pq Vt "struct rwlock" -An -.Xr rwlock 9 -lock used to protect -.Va if_afdata -internals. -.It Va if_linktask -.Pq Vt "struct task" -A -.Xr taskqueue 9 -task scheduled for link state change events of the interface. -.It Va if_addr_lock -.Pq Vt "struct rwlock" -An -.Xr rwlock 9 -lock used to protect interface-related address lists. -.It Va if_clones -.Pq Fn LIST_ENTRY ifnet -.Xr queue 3 -macro glue for the list of clonable network interfaces. -.It Va if_groups -.Pq Fn TAILQ_HEAD "" "ifg_list" -The head of the -.Xr queue 3 -.Li TAILQ -containing the list of groups per interface. -.It Va if_pf_kif -.Pq Vt "void *" -A pointer to the structure used for interface abstraction by -.Xr pf 4 . -.It Va if_lagg -.Pq Vt "void *" -A pointer to the -.Xr lagg 4 -interface structure. -.It Va if_alloctype -.Pq Vt u_char +This is initialized by +.Fn if_alloc . +.It Fn if_getidxgen +.It Fn if_getdname Fn if_setdname +.Pq Ft "const char *" +The name of the driver. +This is initialized by driver +(usually via +.Fn if_initname ) . +.It Fn if_name Fn if_setname +.Pq Vt "char *" +The name of the interface, +(e.g., +.Ql fxp0 +or +.Dq Li lo0 ) . +This is initialized by driver, usually via +.Fn if_initname . +.It Fn if_getalloctype +.Pq Ft u_char The type of the interface as it was at the time of its allocation. It is used to cache the type passed to .Fn if_alloc , but unlike .Va if_type , it would not be changed by drivers. -.It Va if_numa_domain +.It Fn if_gettype +.It Fn if_setdev +.It Fn if_getdrvflags Fn if_setdrvflags Fn if_setdrvflagbits +.It Fn if_getlinkstate +.It Fn if_clearhwassist Fn if_sethwassistbits +.Fn if_gethwassist Fn if_sethwassist Fn if_togglehwassist +.Pq Vt u_long +A detailed interpretation of the capabilities +to offload computational tasks for +.Em outgoing +packets. +The interface driver must keep this field in accord with +the current value of +.Va if_capenable . +.It Fn if_getsoftc Fn if_setsoftc +.Pq Ft "void *" +A pointer to the driver's private state block. +This is initialized by driver at attach. +.It Fn if_setllsoftc +.It Fn if_getllsoftc +.It Fn if_getfib +.It Fn if_getaddrlen +.It Fn if_gethwaddr +.It Fn if_getbroadcastaddr Fn if_setbroadcastaddr +Access the interface broadcast addess. +.It Fn if_setmtu +.It Fn if_getmtu +Access the interface MTU. +.It Fn if_setflags Fn if_getflags Fn if_setflagbits +.Pq Vt int +Flags describing operational parameters of this interface (see below). +These flags are manipulated by generic code. +.It Fn if_getnumadomain .Pq Vt uint8_t The NUMA domain of the hardware device associated with the interface. This is filled in with a wildcard value unless the kernel is NUMA @@ -450,6 +499,63 @@ using .Fn if_alloc_dev or .Fn if_alloc_domain . +.It Fn if_sendq_empty +.It Fn if_setsendqready +.It Fn if_setsendqlen +.It Fn if_sethwtsomax Fn if_gethwtsomax +.It Fn if_sethwtsomaxsegcount Fn if_gethwtsomaxsegcount +.It Fn if_sethwtsomaxsegsize Fn if_gethwtsomaxsegsize +.It Fn if_setnetmapadapter Fn if_getnetmapadapter +.It Fn if_setifheaderlen +.It Fn if_setrcvif +.It Fn if_setvtag Fn if_getvtag +.It Fn if_vlantrunkinuse +.It Fn if_getlladdr +.It Fn if_getvnet +.Pq Vt "struct vnet *" +A pointer to the virtual network stack instance. +This is initialized by +.Fn if_attach . +.It Fn if_gethandle +.It Fn if_vlancap +.It Fn if_getcounter +.It Fn if_getmaclabel Fn if_setmaclabel +.It Fn if_getbpf +.Pq Ft "struct bpf_if *" +Opaque per-interface data for the packet filter, +.Xr bpf 4 . +This is initialized by +.Fn bpf_attach . +.It Fn if_getpcp +.It Fn if_getl2com +A pointer to the common data for the interface's layer 2 protocol. +This is initialized by +.Fn if_alloc . +.Fn if_getvlantrunk "if_t ifp" +.Pq Ft struct ifvlantrunk * +A pointer to 802.1Q trunk structure, +.Xr vlan 4 . +This is initialized by the driver-specific +.Fn if_ioctl +routine. +.It Fn if_getdrvflags Fn if_setdrvflags Fn if_setdrvflagbits +.Pq Ft int +Flags describing operational status of this interface (see below). +These flags are manipulated by driver. +.It Fn if_addmulti Fn if_delmulti Fn if_findmulti +Add, remove, and find multicast addresses assigned to this interface. +.It Fn if_getifaddr +.Pq Vt "struct ifaddr *" +Get a pointer to the interface's link-level address. +.It Fn if_getbroadcastaddr Fn if_setbroadcastaddr +.Pq Ft "const u_int8_t *" +A link-level broadcast bytestring for protocols with variable address +length. +.It Fn if_getafdata +.Pq Ft "void *" +An address family dependent data region. +.It Fn if_addgroup Fn if_delgroup +Add and delete groups from the interface. .El .Pp References to @@ -612,6 +718,10 @@ This interface is in the permanently promiscuous mode (implies .It Dv IFF_ALLMULTI .Aq D* This interface is in all-multicasts mode (used by multicast routers). +.It Dv IFF_PALLMULTI +.Aq D +This interface is in the permanently all-multicasts mode (implies +.Dv IFF_ALLMULTI ) . .It Dv IFF_DRV_OACTIVE .Aq D* The interface's hardware output queue (if any) is full; output packets @@ -891,18 +1001,6 @@ link-layer overhead. .It Va ifi_metric .Pq Vt u_long A dimensionless metric interpreted by a user-mode routing process. -.It Va ifi_baudrate -.Pq Vt u_long -The line rate of the interface, in bits per second. -.It Va ifi_hwassist -.Pq Vt u_long -A detailed interpretation of the capabilities -to offload computational tasks for -.Em outgoing -packets. -The interface driver must keep this field in accord with -the current value of -.Va if_capenable . .It Va ifi_epoch .Pq Vt time_t The system uptime when interface was attached or the statistics @@ -961,8 +1059,7 @@ Number of packets received for unknown network-layer protocol. .It Va ifi_lastchange .Pq Vt "struct timeval" The time of the last administrative change to the interface (as required -for -.Tn SNMP ) . +for SNMP ) . .El .Ss Interface Types The header file @@ -997,7 +1094,7 @@ interface Serial Line IP .It Dv IFT_PARA Parallel-port IP -.Pq Dq Tn PLIP +.Pq Dq PLIP .It Dv IFT_ATM Asynchronous Transfer Mode .It Dv IFT_USB @@ -1062,7 +1159,7 @@ is a macro for The network mask for multi-access interfaces, and the confusion generator for point-to-point interfaces. .It Va ifa_ifp -.Pq Vt "struct ifnet *" +.Pq Vt "if_t" A link back to the interface structure. .It Va ifa_link .Pq Fn TAILQ_ENTRY ifaddr @@ -1183,9 +1280,7 @@ structure to be the first element in that list. (A pointer to this address structure is saved in the .Vt ifnet -structure and is accessed by the -.Fn ifaddr_byindex -function.) +structure.) The .Fa ifp must have been allocated by @@ -1326,7 +1421,7 @@ and appropriately. .Pp .It Dv SIOCGIFCAPNV -.Xr NV 9 +.Xr nv 9 version of the .Dv SIOCGIFCAP ioctl. @@ -1370,7 +1465,7 @@ non-modifiable capability bit in .Dv if_capabilities . .Pp .It Dv SIOCSIFCAPNV -.Xr NV 9 +.Xr nv 9 version of the .Dv SIOCSIFCAP ioctl. @@ -1502,10 +1597,6 @@ precisely .Fa addr will be returned. .Pp -.Fn ifaddr_byindex -returns the link-level address of the interface with the given index -.Fa idx . -.Pp All of these functions return a null pointer if no such address can be found. .Ss "Interface Multicast Address Functions" diff --git a/share/man/man9/intr_event.9 b/share/man/man9/intr_event.9 index d1964ce289a5..ba8faf877e6a 100644 --- a/share/man/man9/intr_event.9 +++ b/share/man/man9/intr_event.9 @@ -27,7 +27,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd October 30, 2022 +.Dd January 24, 2025 .Dt INTR_EVENT 9 .Os .Sh NAME @@ -295,6 +295,14 @@ from the handler's source triggers. Presently, the .Dv INTR_ENTROPY flag is not valid for software interrupt handlers. +The +.Dv INTR_SLEEPABLE +flag specifies that the interrupt ithread may sleep. +Presently, the +.Dv INTR_SLEEPABLE +flag requires the +.Dv INTR_EXCL +flag to be set. .Ss Handler Callbacks Each .Vt struct intr_event diff --git a/share/man/man9/khelp.9 b/share/man/man9/khelp.9 index 39515eef237c..d619f385d513 100644 --- a/share/man/man9/khelp.9 +++ b/share/man/man9/khelp.9 @@ -27,7 +27,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd February 15, 2011 +.Dd October 1, 2024 .Dt KHELP 9 .Os .Sh NAME @@ -48,8 +48,8 @@ .Fn "int khelp_destroy_osd" "struct osd *hosd" .Fn "int32_t khelp_get_id" "char *hname" .Fn "void * khelp_get_osd" "struct osd *hosd" "int32_t id" -.Fn "int khelp_add_hhook" "struct hookinfo *hki" "uint32_t flags" -.Fn "int khelp_remove_hhook" "struct hookinfo *hki" +.Fn "int khelp_add_hhook" "const struct hookinfo *hki" "uint32_t flags" +.Fn "int khelp_remove_hhook" "const struct hookinfo *hki" .Fn KHELP_DECLARE_MOD "hname" "hdata" "hhooks" "version" .Fn KHELP_DECLARE_MOD_UMA "hname" "hdata" "hhooks" "version" "ctor" "dtor" .Sh DESCRIPTION diff --git a/share/man/man9/lock.9 b/share/man/man9/lock.9 index 110fdd68fda0..9cff6e3bd8aa 100644 --- a/share/man/man9/lock.9 +++ b/share/man/man9/lock.9 @@ -24,7 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" -.Dd November 17, 2017 +.Dd June 21, 2024 .Dt LOCK 9 .Os .Sh NAME @@ -34,9 +34,14 @@ .Nm lockmgr_args , .Nm lockmgr_args_rw , .Nm lockmgr_disown , +.Nm lockmgr_disowned , +.Nm lockmgr_lock_flags , .Nm lockmgr_printinfo , .Nm lockmgr_recursed , .Nm lockmgr_rw , +.Nm lockmgr_slock , +.Nm lockmgr_unlock , +.Nm lockmgr_xlock , .Nm lockstatus , .Nm lockmgr_assert .Nd "lockmgr family of functions" @@ -56,6 +61,10 @@ .Fn lockmgr_args_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" "const char *wmesg" "int prio" "int timo" .Ft void .Fn lockmgr_disown "struct lock *lkp" +.Ft int +.Fn lockmgr_disowned "const struct lock *lkp" +.Ft int +.Fn lockmgr_lock_flags "struct lock *lkp" "u_int flags" "struct lock_object *ilk" "const char *file" "int line" .Ft void .Fn lockmgr_printinfo "const struct lock *lkp" .Ft int @@ -63,6 +72,12 @@ .Ft int .Fn lockmgr_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" .Ft int +.Fn lockmgr_slock "struct lock *lkp" "u_int flags" "const char *file" "int line" +.Ft int +.Fn lockmgr_unlock "struct lock *lkp" +.Ft int +.Fn lockmgr_xlock "struct lock *lkp" "u_int flags" "const char *file" "int line" +.Ft int .Fn lockstatus "const struct lock *lkp" .Pp .Cd "options INVARIANTS" @@ -108,10 +123,6 @@ should log messages about duplicate locks being acquired. Disable .Xr ktr 4 logging for this lock. -.It Dv LK_TIMELOCK -Use -.Fa timo -during a sleep; otherwise, 0 is used. .El .El .Pp @@ -182,6 +193,10 @@ Fail if operation has slept. .It Dv LK_NOWAIT Do not allow the call to sleep. This can be used to test the lock. +.It Dv LK_TIMELOCK +Use +.Fa timo +during a sleep; otherwise, 0 is used. .It Dv LK_NOWITNESS Skip the .Xr witness 4 @@ -253,12 +268,55 @@ and .Dv LK_TIMO_DEFAULT . .Pp The +.Fn lockmgr_lock_flags +function works like +.Fn lockmgr +but accepts explicit +.Fa file +and +.Fa line +arguments for lock tracing. +.Pp +The +.Fn lockmgr_slock , +.Fn lockmgr_xlock , +and +.Fn lockmgr_unlock +functions are lightweight entry points that function like +.Fn lockmgr +for the +.Dv LK_SHARED , +.Dv LK_EXCLUSIVE , +and +.Dv LK_RELEASE +operations respectively. +They provide functionality similar to +.Xr sx 9 +locks in that none of the additional +.Xr lockmgr 9 +features are supported. +Specifically, these functions do not support unlocking interlocks, the +.Dv LK_SLEEPFAIL +flag, or locks with shared locking disabled via +.Dv LK_NOSHARE . +They also accept explicit +.Fa file +and +.Fa line +arguments for lock tracing. +.Pp +The .Fn lockmgr_disown function switches the owner from the current thread to be .Dv LK_KERNPROC , if the lock is already held. .Pp The +.Fn lockmgr_disowned +function returns true or false according to whether the lock is held by +.Dv LK_KERNPROC . +.Pp +The .Fn lockmgr_printinfo function prints debugging information about the lock. It is used primarily by @@ -354,6 +412,8 @@ was requested and another thread had already requested a lock upgrade. was set, and a sleep would have been required, or .Dv LK_TRYUPGRADE operation was not able to upgrade the lock. +.It Bq Er EDEADLK +A shared lock was attempted while the thread already held the exclusive lock. .It Bq Er ENOLCK .Dv LK_SLEEPFAIL was set and @@ -398,6 +458,7 @@ exclusive lock, and a .Xr panic 9 will be the result of trying. .Sh SEE ALSO +.Xr witness 4 , .Xr condvar 9 , .Xr locking 9 , .Xr mtx_assert 9 , diff --git a/share/man/man9/make_dev.9 b/share/man/man9/make_dev.9 index 2beb38586593..de56f350faa5 100644 --- a/share/man/man9/make_dev.9 +++ b/share/man/man9/make_dev.9 @@ -1,3 +1,6 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" .\" Copyright (c) 1999 Chris Costello .\" All rights reserved. .\" @@ -22,7 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd March 2, 2016 +.Dd January 19, 2025 .Dt MAKE_DEV 9 .Os .Sh NAME @@ -38,9 +41,7 @@ .Nm destroy_dev_sched_cb , .Nm destroy_dev_drain , .Nm dev_depends -.Nd manage -.Vt cdev Ns 's -and DEVFS registration for devices +.Nd create and destroy character devices including devfs registration .Sh SYNOPSIS .In sys/param.h .In sys/conf.h @@ -81,7 +82,7 @@ structure for a new device, which is returned into the .Fa cdev argument. It also notifies -.Xr devfs 5 +.Xr devfs 4 of the presence of the new device, that causes corresponding nodes to be created. Besides this, a @@ -105,6 +106,7 @@ struct make_dev_args { void *mda_si_drv2; }; .Ed +.Pp Before use and filling with the desired values, the structure must be initialized by the .Fn make_dev_args_init @@ -123,7 +125,7 @@ would print it. The name determines its path under .Pa /dev or other -.Xr devfs 5 +.Xr devfs 4 mount point and may contain slash .Ql / characters to denote subdirectories. @@ -166,10 +168,10 @@ member of the initialized The .Va args.mda_flags argument alters the operation of -.Fn make_dev_s. +.Fn make_dev_s . The following values are currently accepted: .Pp -.Bl -tag -width "It Dv MAKEDEV_CHECKNAME" -compact -offset indent +.Bl -tag -width "MAKEDEV_CHECKNAME" -compact -offset indent .It Dv MAKEDEV_REF reference the created device .It Dv MAKEDEV_NOWAIT @@ -200,12 +202,13 @@ is specified. .Pp The .Xr dev_clone 9 -event handler shall specify +event handler shall specify the .Dv MAKEDEV_REF -flag when creating a device in response to lookup, to avoid race where -the device created is destroyed immediately after -.Xr devfs_lookup 9 -drops his reference to cdev. +flag when creating a device in response to lookup, to avoid a race where +the created device is immediately destroyed after +.Fn devfs_lookup +drops its reference to +.Fa cdev . .Pp The .Dv MAKEDEV_ETERNAL @@ -226,13 +229,14 @@ and the device name is invalid or already exists. .Pp The .Fn make_dev_p -use of the form +use of the form: .Bd -literal -offset indent struct cdev *dev; int res; res = make_dev_p(flags, &dev, cdevsw, cred, uid, gid, perms, name); .Ed -is equivalent to the code +.Pp +is equivalent to the code: .Bd -literal -offset indent struct cdev *dev; struct make_dev_args args; @@ -241,7 +245,7 @@ int res; make_dev_args_init(&args); args.mda_flags = flags; args.mda_devsw = cdevsw; -args.mda_cred = cred; +args.mda_cr = cred; args.mda_uid = uid; args.mda_gid = gid; args.mda_mode = perms; @@ -250,10 +254,11 @@ res = make_dev_s(&args, &dev, name); .Pp Similarly, the .Fn make_dev_credf -function call is equivalent to +function call is equivalent to: .Bd -literal -offset indent - (void) make_dev_s(&args, &dev, name); +(void) make_dev_s(&args, &dev, name); .Ed +.Pp In other words, .Fn make_dev_credf does not allow the caller to obtain the return value, and in @@ -263,14 +268,14 @@ options, the function asserts that the device creation succeeded. .Pp The .Fn make_dev_cred -function is equivalent to the call +function is equivalent to the call: .Bd -literal -offset indent make_dev_credf(0, cdevsw, unit, cr, uid, gid, perms, fmt, ...); .Ed .Pp The .Fn make_dev -function call is the same as +function call is the same as: .Bd -literal -offset indent make_dev_credf(0, cdevsw, unit, NULL, uid, gid, perms, fmt, ...); .Ed @@ -377,7 +382,7 @@ is called, with argument .Fa arg . The .Fn destroy_dev_sched -function is the same as +function is the same as: .Bd -literal -offset indent destroy_dev_sched_cb(cdev, NULL, NULL); .Ed @@ -457,7 +462,7 @@ flag was specified and the provided device name already exists. .El .Sh SEE ALSO .Xr devctl 4 , -.Xr devfs 5 , +.Xr devfs 4 , .Xr dev_clone 9 .Sh HISTORY The diff --git a/share/man/man9/malloc.9 b/share/man/man9/malloc.9 index 0ab5b2ed6e8d..01d224fc3cb3 100644 --- a/share/man/man9/malloc.9 +++ b/share/man/man9/malloc.9 @@ -28,7 +28,7 @@ .\" .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ .\" -.Dd October 12, 2022 +.Dd August 4, 2024 .Dt MALLOC 9 .Os .Sh NAME @@ -269,6 +269,15 @@ This option should only be used in combination with .Dv M_NOWAIT when an allocation failure cannot be tolerated by the caller without catastrophic effects on the system. +.It Dv M_NEVERFREED +This is an internal flag used by the +.Xr uma 9 +allocator and should not be used in regular +.Fn malloc +invocations. +See the description of VM_ALLOC_NOFREE in +.Xr vm_page_alloc 9 +for more details. .El .Pp Exactly one of either diff --git a/share/man/man9/mbuf.9 b/share/man/man9/mbuf.9 index 0b03d697b8bf..c05505716a30 100644 --- a/share/man/man9/mbuf.9 +++ b/share/man/man9/mbuf.9 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 28, 2023 +.Dd July 29, 2025 .Dt MBUF 9 .Os .\" @@ -1091,7 +1091,7 @@ network code, when data must be encrypted or otherwise altered prior to transmission. .El .Sh HARDWARE-ASSISTED CHECKSUM CALCULATION -This section currently applies to TCP/IP only. +This section currently applies to SCTP, TCP, and UDP over IP only. In order to save the host CPU resources, computing checksums is offloaded to the network interface hardware if possible. The @@ -1117,7 +1117,7 @@ in the .Vt mbuf chain containing the packet. .Pp -On output, checksum offloading is attempted after the outgoing +On output, the computation of the checksum is delayed until the outgoing interface has been determined for a packet. The interface-specific field .Va ifnet.if_data.ifi_hwassist @@ -1135,12 +1135,15 @@ such actions will never be requested through .Va csum_flags . .Pp The flags demanding a particular action from an interface are as follows: -.Bl -tag -width ".Dv CSUM_TCP" -offset indent +.Bl -tag -width ".Dv CSUM_SCTP" -offset indent .It Dv CSUM_IP The IP header checksum is to be computed and stored in the corresponding field of the packet. The hardware is expected to know the format of an IP header to determine the offset of the IP checksum field. +.It Dv CSUM_SCTP +The SCTP checksum is to be computed. +(See below.) .It Dv CSUM_TCP The TCP checksum is to be computed. (See below.) @@ -1149,14 +1152,16 @@ The UDP checksum is to be computed. (See below.) .El .Pp -Should a TCP or UDP checksum be offloaded to the hardware, +Should a SCTP, TCP, or UDP checksum be offloaded to the hardware, the field .Va csum_data will contain the byte offset of the checksum field relative to the end of the IP header. -In this case, the checksum field will be initially -set by the TCP/IP module to the checksum of the pseudo header +In the case of TCP or UDP, the checksum field will be initially +set by the TCP or UDP implementation to the checksum of the pseudo header defined by the TCP and UDP specifications. +In the case of SCTP, the checksum field will be initially +set by the SCTP implementation to 0. .Pp On input, an interface indicates the actions it has performed on a packet by setting one or more of the following flags in @@ -1187,13 +1192,13 @@ to obtain the final checksum to be used for TCP or UDP validation purposes. .El .Pp If a particular network interface just indicates success or -failure of TCP or UDP checksum validation without returning +failure of SCTP, TCP, or UDP checksum validation without returning the exact value of the checksum to the host CPU, its driver can mark .Dv CSUM_DATA_VALID -and -.Dv CSUM_PSEUDO_HDR in -.Va csum_flags , +.Va csum_flags +as well as, for TCP and UDP, +.Dv CSUM_PSEUDO_HDR and set .Va csum_data to @@ -1203,6 +1208,13 @@ It is a peculiarity of the algorithm used that the Internet checksum calculated over any valid packet will be .Li 0xFFFF as long as the original checksum field is included. +Note that for SCTP the value of +.Va csum_data +is not relevant and +.Dv CSUM_PSEUDO_HDR +in +.Va csum_flags +is not set, since SCTP does not use a pseudo header checksum. .Sh STRESS TESTING When running a kernel compiled with the option .Dv MBUF_STRESS_TEST , @@ -1212,7 +1224,7 @@ the following various failure/extreme cases for testing of network drivers and other parts of the kernel that rely on .Vt mbufs . -.Bl -tag -width ident +.Bl -tag -width indent .It Va net.inet.ip.mbuf_frag_size Causes .Fn ip_output diff --git a/share/man/man9/mi_switch.9 b/share/man/man9/mi_switch.9 index 549ec497434c..e04c2ee35ace 100644 --- a/share/man/man9/mi_switch.9 +++ b/share/man/man9/mi_switch.9 @@ -31,23 +31,17 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd January 9, 2023 +.Dd January 7, 2025 .Dt MI_SWITCH 9 .Os .Sh NAME -.Nm mi_switch , -.Nm cpu_switch , -.Nm cpu_throw +.Nm mi_switch .Nd switch to another thread context .Sh SYNOPSIS .In sys/param.h .In sys/proc.h .Ft void .Fn mi_switch "int flags" -.Ft void -.Fn cpu_switch "struct thread *oldtd" "struct thread *newtd" "struct mtx *lock" -.Ft void -.Fn cpu_throw "struct thread *oldtd" "struct thread *newtd" .Sh DESCRIPTION The .Fn mi_switch @@ -168,63 +162,9 @@ running thread .Fa oldtd to the chosen thread .Fa newtd . -First, it saves the context of -.Fa oldtd -to its Process Control Block -.Po -PCB, -.Vt struct pcb -.Pc , -pointed at by -.Va oldtd->td_pcb . -The function then updates important per-CPU state such as the -.Dv curthread -variable, and activates -.Fa newtd\&'s -virtual address space using its associated -.Xr pmap 9 -structure. -Finally, it reads in the saved context from -.Fa newtd\&'s -PCB. -CPU instruction flow continues in the new thread context, on -.Fa newtd\&'s -kernel stack. -The return from -.Fn cpu_switch -can be understood as a completion of the function call initiated by -.Fa newtd -when it was previously switched out, at some point in the distant (relative to -CPU time) past. -.Pp -The -.Fa mtx -argument to -.Fn cpu_switch -is used to pass the mutex which will be stored as -.Fa oldtd\&'s -thread lock at the moment that -.Fa oldtd -is completely switched out. -This is an implementation detail of -.Fn sched_switch . -.Pp -.Fn cpu_throw -is similar to -.Fn cpu_switch -except that it does not save the context of the old thread. -This function is useful when the kernel does not have an old thread -context to save, such as when CPUs other than the boot CPU perform their -first task switch, or when the kernel does not care about the state of the -old thread, such as in -.Xr thread_exit 9 -when the kernel terminates the current thread and switches into a new -thread, -.Fa newtd . -The -.Fa oldtd -argument is unused. .Sh SEE ALSO +.Xr cpu_switch 9 , +.Xr cpu_throw 9 , .Xr critical_exit 9 , .Xr issignal 9 , .Xr kern_yield 9 , diff --git a/share/man/man9/mod_cc.9 b/share/man/man9/mod_cc.9 index 86d9c7b5312c..09580aa943a9 100644 --- a/share/man/man9/mod_cc.9 +++ b/share/man/man9/mod_cc.9 @@ -370,7 +370,7 @@ LRO system. So for example if LRO pushed three in-order acknowledgements into one acknowledgement the variable would be set to three. .Pp -The +The .Va labc variable is used in conjunction with the CCF_USE_LOCAL_ABC flag to override what labc variable the congestion controller will use diff --git a/share/man/man9/namei.9 b/share/man/man9/namei.9 index 0be73f68cdda..5bdffce8c360 100644 --- a/share/man/man9/namei.9 +++ b/share/man/man9/namei.9 @@ -31,13 +31,14 @@ .\" If you integrate this manpage in another OS, I'd appreciate a note .\" - eivind@FreeBSD.org .\" -.Dd July 8, 2023 +.Dd May 16, 2025 .Dt NAMEI 9 .Os .Sh NAME .Nm namei , .Nm NDINIT , -.Nm NDFREE +.Nm NDINIT_AT , +.Nm NDFREE_PNBUF .Nd pathname translation and lookup operations .Sh SYNOPSIS .In sys/param.h @@ -47,11 +48,16 @@ .Fn namei "struct nameidata *ndp" .Ft void .Fo NDINIT -.Fa "struct nameidata *ndp" "u_long op" "u_long flags" -.Fa "enum uio_seg segflg" "const char *namep" "struct thread *td" +.Fa "struct nameidata *ndp" "enum nameiop op" "u_int64_t flags" +.Fa "enum uio_seg segflg" "const char *namep" .Fc .Ft void -.Fn NDFREE "struct nameidata *ndp" "const uint flags" +.Fo NDINIT_AT +.Fa "struct nameidata *ndp" "enum nameiop op" "u_int64_t flags" +.Fa "enum uio_seg segflg" "const char *namep" "int dirfd" +.Fc +.Ft void +.Fn NDFREE_PNBUF "struct nameidata *ndp" .Sh DESCRIPTION The .Nm @@ -71,13 +77,13 @@ flag was specified or not. .Pp The .Fn NDINIT -function is used to initialize +macro is used to initialize .Nm components. It takes the following arguments: .Bl -tag -width ".Fa segflg" .It Fa ndp -The +A pointer to the .Vt "struct nameidata" to initialize. .It Fa op @@ -95,7 +101,7 @@ will not result in .Fn VOP_RENAME being called. .It Fa flags -Operation flags. +Operation flags, described in the next section. Several of these can be effective at the same time. .It Fa segflg UIO segment indicator. @@ -106,10 +112,35 @@ or in the kernel address space .It Fa namep Pointer to the component's pathname buffer (the file or directory name that will be looked up). -.It Fa td -The thread context to use for -.Nm -operations and locks. +.El +.Pp +The +.Fn NDINIT_AT +macro is similar to +.Fn NDINIT , +but takes one extra argument: +.Bl -tag -width ".Fa segflg" +.It Fa dirfd +File descriptor referencing a directory, or the special value +.Dv AT_FDCWD +meaning the calling thread's current working directory. +Lookups will be performed relative to this directory. +.El +.Pp +The +.Fn NDFREE_PNBUF +macro is used to free the pathname buffer. +It must be called exactly once for each successful +.Fn namei +call. +It takes the following argument: +.Bl -tag -width ".Fa segflg" +.It Fa ndp +A pointer to a +.Vt "struct nameidata" +that was used in a successful +.Fn namei +call. .El .Sh NAMEI OPERATION FLAGS The @@ -117,14 +148,32 @@ The function takes the following set of .Dq "operation flags" that influence its operation: -.Bl -tag -width ".Dv WANTPARENT" +.Bl -tag -width NC_KEEPPOSENTRY +.It Dv NC_NOMAKEENTRY +An alias for +.Dv NOCACHE . +.It Dv NC_KEEPPOSENTRY +Keep the positive-caching entry in cache. +This flag is typically combined with +.Dv NOCACHE +to not cache a new entry, +but keep existing one, or with +.Dv MAKEENTRY . +.It Dv NOCACHE +Avoid +.Fn namei +creating this entry in the namecache if it is not +already present. +Normally, +.Fn namei +will add entries to the name cache +if they are not already there. .It Dv LOCKLEAF Lock vnode on return with .Dv LK_EXCLUSIVE unless .Dv LOCKSHARED is also set. -The .Xr VOP_UNLOCK 9 should be used to release the lock (or @@ -151,40 +200,70 @@ or .Xr VOP_UNLOCK 9 and .Xr vrele 9 . -.It Dv LOCKSHARED -Lock vnode on return with -.Dv LK_SHARED . -The -.Xr VOP_UNLOCK 9 -should be used -to release the lock (or -.Xr vput 9 -which is equivalent to calling -.Xr VOP_UNLOCK 9 -followed by -.Xr vrele 9 , -all in one). .It Dv WANTPARENT This flag allows the .Fn namei function to return the parent (directory) vnode in an unlocked state. The parent vnode must be released separately by using .Xr vrele 9 . -.It Dv NOCACHE -Avoid -.Fn namei -creating this entry in the namecache if it is not -already present. -Normally, +.It Dv WANTPARENT +This flag allows the .Fn namei -will add entries to the name cache -if they are not already there. +function to return the parent (directory) vnode in an unlocked state. +The parent vnode must be released separately by using +.Xr vrele 9 . +.It Dv FAILIFEXISTS +Makes the +.Nm +operation fail if the target exists. +It requires that the +.Dv LOCKPARENT +flag is set and +.Dv LOCKLEAF +is not. .It Dv FOLLOW With this flag, .Fn namei will follow the symbolic link if the last part of the path supplied is a symbolic link (i.e., it will return a vnode for whatever the link points at, instead for the link itself). +.It Dv EMPTYPATH +For +.Nm +call initialized with +.Fn NDINIT_AT , +allow the +.Fa namep +path to be empty. +In this case, the +.Fa dirfd +file descriptor may reference a file of arbitrary type, not +necessary a directory, and lookup returns the vnode for this file. +.It Dv LOCKSHARED +Lock vnode on return with +.Dv LK_SHARED , +if permitted by the file system that owns the vnode. +The file system must explicitly permit this by setting +.Dv MNTK_LOOKUP_SHARED +in +.Dv mp->mnt_kern_flag +during mount and by calling +.Fn VN_LOCK_ASHARE +when allocating the vnode. +If +.Dv LOCKLEAF +is specified but shared locking is not permitted, then the vnode will be +returned with +.Dv LK_EXCLUSIVE . +.Xr VOP_UNLOCK 9 +should be used +to release the lock (or +.Xr vput 9 +which is equivalent to calling +.Xr VOP_UNLOCK 9 +followed by +.Xr vrele 9 , +all in one). .It Dv NOFOLLOW Do not follow symbolic links (pseudo). This flag is not looked for by the actual code, which looks for @@ -192,17 +271,131 @@ This flag is not looked for by the actual code, which looks for .Dv NOFOLLOW is used to indicate to the source code reader that symlinks are intentionally not followed. -.It Dv SAVENAME -Do not free the pathname buffer at the end of the -.Fn namei -invocation; instead, free it later in -.Fn NDFREE -so that the caller may access the pathname buffer. -See below for details. -.It Dv SAVESTART -Retain an additional reference to the parent directory; do not free -the pathname buffer. -See below for details. +.It Dv RBENEATH +Requires that +.Nm +did not cross the +.Fa dirfd +directory. +The flag is used to implement +.Dv O_RESOLVE_BENEATH +flag for +.Xr openat 2 . +.It Dv NAMEILOOKUP +The component is embedded in a +.Nm +lookup structure, and the +.Fn vfs_lookup_nameidata +function can be used to obtain that structure. +This can be useful in +.Xr VOP_LOOKUP 9 +implementations which need to obtain extra lookup metadata. +.El +.Sh PARAMETERS DESCRIPTORS FLAGS +These flags are used for several purposes. +Some of them affects the global +.Nm +operation, some provide information for processing of the specific +path element, for instance, by the +.Dv VOP_LOOKUP +implementation of the involved filesystem. +.Bl -tag -width IGNOREWHITEOUT +.It Dv RDONLY +Specifies that the lookup should act as if the final node is located on +read-only mount. +The flag is typically used by file servers, e.g. NFS, +to handle read-only exports. +.It Dv ISRESTARTED +The +.Nm +was restarted with +.Fn NDRESTART . +This is used internally for double-root lookups used by ABI subsystems, +after the lookup with native root failed. +The components are reset to the original values, and lookup is repeated +with different root, once. +.It Dv IGNOREWHITEOUT +Ignore whiteouts, e.g. when checking if a directory is empty. +.It Dv ISWHITEOUT +The result of lookup is whiteout. +.It Dv DOWHITEOUT +Handle whiteouts, the instruction for the +.Fn VOP_LOOKUP +filesystem methods. +.It Dv WILLBEDIR +The lookup is done for creating a new entry that will be directory. +It allows the trailing slash in the path string. +.It Dv ISOPEN +The caller is the code that opens a file. +This allows to weaken the lock mode of the return vnode, if the +mount point indicates extended shared lock support. +.It Dv NOCROSSMOUNT +Do not cross mount points during lookup. +.Pp +For +.Dq .. +lookup leading to mount root, returns the root vnode of +the mount instead of the covered vnode of the filesystem where +the mount was placed. +.Pp +For other lookups passing over mount, do not jump into the mounted +filesystem. +This allows to descend into the file hierarchy otherwise shadowed +by the mount point. +.It Dv NOMACCHECK +Do not perform MAC checks during lookup. +.It Dv AUDITVNODE1 +Audit the looked up vnode information, use the first slot for audit information. +.It Dv AUDITVNODE2 +Same as +.Dv AUDITVNODE1 +but use the second slot. +.It Dv NOCAPCHECK +Do not perform capability checks. +If the calling process is in capability mode, lookup is denied outright. +.It Dv OPENREAD +The lookup was for open and file will be opened for read. +.It Dv OPENWRITE +The lookup was for open and file will be opened for write. +.It Dv WANTIOCTLCAPS +Leave ioctl caps for the caller. +See the description of +.Nm +results. +.It Dv OPENNAMED +Opening a named attribute (directory). +.It Dv NOEXECCHECK +Do not perform check for allowed execution on the starting directory. +It is used to implement the POSIX-required semantic for +.Xr openat 2 +lookups that must use the permissions from time the directory was +opened, and not when used for lookup. +.It Dv MAKEENTRY +Looked-up entry is to be added to name cache. +.It Dv ISSYMLINK +Current component is symlink, and it needs the interpretation +according to the +.Dv FOLLOW +or +.Dv NOFOLLOW +flags. +.It Dv ISLASTCN +This is last component of pathname. +It is handled specially, many flags augment its processing. +.It Dv ISDOTDOT +Current component name is +.Dq .. . +Usually implies a need to specially handle the vnode locking +for instantiation of the target vnode. +The generic +.Fn vn_vget_ino_gen +function and its more specialized variant +.Fn vn_vget_ino +might be useful. +.It Dv TRAILINGSLASH +Path ended in a slash. +.It Dv CREATENAMED +Create a named attribute dir. .El .Sh ALLOCATED ELEMENTS The @@ -251,6 +444,34 @@ It is managed by the .Xr uma 9 zone allocation interface. .El +.Sh RESULTS +The +.Vt struct namei +member +.Dv ni_resflags +returns the following flags giving some details of the succesfull operation: +.Bl -tag -width NIRES_EMPTYPATH +.It Dv NIRES_ABS +The path passed was absolute. +.It Dv NIRES_STRICTREL +Restricted lookup result. +Only relative lookups were done to resolve the path to vnode. +.It Dv NIRES_EMPTYPATH +The +.Dv EMPTYPATH +flag was provided and used. +In particular, the passed path was empty. +.El +.Pp +If the +.Dv WANTIOCTLCAPS +flag was specified, on return the +.Va ni_filecaps +member of the +.Vt struct namei +contains the capabilities of the file descriptor used as +the lookup starting point +.Pq Va dirfd . .Sh RETURN VALUES If successful, .Fn namei @@ -259,6 +480,24 @@ will return 0, otherwise it will return an error. .Bl -tag -width Pa .It Pa src/sys/kern/vfs_lookup.c .El +.Sh EXAMPLES +Assuming the +.Dv path +variable contains a pointer to userspace path string, the following +example looks up the file named by it, and performs required error +and resource handling: +.Bd -literal + char *path; + struct nameidata nd; + int error; + + NDINIT(&nd, LOOKUP, FOLLOW | LOCKLEAF | AUDITVNODE1, UIO_USERSPACE, + path); + if ((error = namei(&nd)) != 0) + return (error); + NDFREE_PNBUF(&nd); + ... use nd.ni_vp vnode +.Ed .Sh ERRORS Errors which .Fn namei @@ -296,7 +535,8 @@ An attempt is made to modify a file or directory on a read-only file system. .Xr VFS 9 , .Xr vnode 9 , .Xr vput 9 , -.Xr vref 9 +.Xr vref 9 , +.Xr vrele 9 .Sh AUTHORS .An -nosplit This manual page was written by diff --git a/share/man/man9/nv.9 b/share/man/man9/nv.9 index 67c05247fdfb..8c99f1d12200 100644 --- a/share/man/man9/nv.9 +++ b/share/man/man9/nv.9 @@ -27,7 +27,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd February 2, 2023 +.Dd January 3, 2025 .Dt NV 9 .Os .Sh NAME @@ -280,11 +280,12 @@ .Sh DESCRIPTION The .Nm libnv -library allows to easily manage name value pairs as well as send and receive +library permits creating and managing name value pairs as well as +sending and receiving them over sockets. A group (list) of name value pairs is called an .Nm nvlist . -The API supports the following data types: +The API supports the following data types for values: .Bl -ohang -offset indent .It Sy null ( NV_TYPE_NULL ) There is no data associated with the name. @@ -330,7 +331,7 @@ The .Fn nvlist_create function allocates memory and initializes an nvlist. .Pp -The following flag can be provided: +The following flags can be provided: .Pp .Bl -tag -width "NV_FLAG_IGNORE_CASE" -compact -offset indent .It Dv NV_FLAG_IGNORE_CASE @@ -342,28 +343,36 @@ Names in the nvlist do not have to be unique. The .Fn nvlist_destroy function destroys the given nvlist. -Function does nothing if -.Dv NULL -nvlist is provided. -Function never modifies the -.Va errno -global variable. +This function does nothing if +.Fa nvl +is +.Dv NULL . +This function never modifies +.Va errno . .Pp The .Fn nvlist_error -function returns any error value that the nvlist accumulated. -If the given nvlist is -.Dv NULL -the +function returns the first error set on +.Fa nvl . +If +.Fa nvl +is not in the error state, +this function returns zero. +If +.Fa nvl +is +.Dv NULL , .Er ENOMEM -error will be returned. +is returned. .Pp The .Fn nvlist_set_error -function sets an nvlist to be in the error state. +function sets an the error value for +.Fa nvl . Subsequent calls to .Fn nvlist_error -will return the given error value. +will return +.Fa error . This function cannot be used to clear the error state from an nvlist. This function does nothing if the nvlist is already in the error state. .Pp @@ -371,16 +380,24 @@ The .Fn nvlist_empty function returns .Dv true -if the given nvlist is empty and +if +.Fa nvl +is empty and .Dv false otherwise. -The nvlist must not be in error state. +The nvlist must not be in the error state. .Pp The .Fn nvlist_flags -function returns flags used to create the nvlist with the -.Fn nvlist_create -function. +function returns the flags used to create +.Fa nvl +with the +.Fn nvlist_create , +.Fn nvlist_recv , +.Fn nvlist_unpack , +or +.Fn nvlist_xfer +functions. .Pp The .Fn nvlist_in_array @@ -392,7 +409,8 @@ is part of an array that is a member of another nvlist. .Pp The .Fn nvlist_clone -functions clones the given nvlist. +function clones +.Fa nvl . The clone shares no resources with its origin. This also means that all file descriptors that are part of the nvlist will be duplicated with the @@ -401,154 +419,170 @@ system call before placing them in the clone. .Pp The .Fn nvlist_dump -dumps nvlist content for debugging purposes to the given file descriptor +function dumps nvlist content for debugging purposes to the file descriptor .Fa fd . .Pp The .Fn nvlist_fdump -dumps nvlist content for debugging purposes to the given file stream +dumps nvlist content for debugging purposes to the file stream .Fa fp . .Pp The .Fn nvlist_size -function returns the size of the given nvlist after converting it to binary -buffer with the +function returns the size of the binary buffer that would be generated by the .Fn nvlist_pack function. .Pp The .Fn nvlist_pack function converts the given nvlist to a binary buffer. -The function allocates memory for the buffer, which should be freed with the +The function allocates memory for the buffer which should be freed with the .Xr free 3 function. If the .Fa sizep argument is not .Dv NULL , -the size of the buffer will be stored there. -The function returns +the size of the buffer is stored there. +This function returns .Dv NULL in case of an error (allocation failure). If the nvlist contains any file descriptors .Dv NULL will be returned. -The nvlist must not be in error state. +The nvlist must not be in the error state. .Pp The .Fn nvlist_unpack -function converts the given buffer to the nvlist. +function converts a binary buffer to a new nvlist. The .Fa flags -argument defines what type of the top level nvlist is expected to be. -Flags are set up using the -.Fn nvlist_create -function. -If the nvlist flags do not match the flags passed to -.Fn nvlist_unpack , -the nvlist will not be returned. -Every nested nvlist list should be checked using -.Fn nvlist_flags -function. -The function returns +argument has the same meaning as the +.Fa flags +argument passed to +.Fn nvlist_create . +If +.Fa flags +do not match the flags used to create the initial nvlist before it was packed, +this function will fail. +The flags of nested nvlists are not validated by this function. +The caller is responsible for validating the flags on any nested nvlists using +.Fn nvlist_flags . +This function returns the new nvlist on success or .Dv NULL in case of an error. .Pp The .Fn nvlist_send -function sends the given nvlist over the socket given by the -.Fa sock -argument. -Note that nvlist that contains file descriptors can only be send over +function sends +.Fa nvl +over the socket +.Fa sock . +Note that nvlists that contain file descriptors can only be sent over .Xr unix 4 domain sockets. .Pp The .Fn nvlist_recv -function receives nvlist over the socket given by the -.Fa sock -argument. -The +function receives an nvlist over the socket +.Fa sock . +As with +.Fn nvlist_unpack , +the .Fa flags -argument defines what type of the top level nvlist is expected to be. -Flags are set up using the -.Fn nvlist_create -function. -If the nvlist flags do not match the flags passed to -.Fn nvlist_recv , -the nvlist will not be returned. -Every nested nvlist list should be checked using -.Fn nvlist_flags -function. +argument is used to construct the new nvlist and must match the flags used +to construct the original nvlist written to +.Fa sock +by the peer. +The flags of nested nvlists are not validated by this function. +The caller is responsible for validating the flags on any nested nvlists using +.Fn nvlist_flags . +This function returns the new nvlist on success or +.Dv NULL +in case of an error. .Pp The .Fn nvlist_xfer -function sends the given nvlist over the socket given by the +function sends +.Fa nvl +over the socket .Fa sock -argument and receives nvlist over the same socket. +argument and then receives a new nvlist over the same socket. The .Fa flags -argument defines what type of the top level nvlist is expected to be. -Flags are set up using the -.Fn nvlist_create -function. -If the nvlist flags do not match the flags passed to -.Fn nvlist_xfer , -the nvlist will not be returned. -Every nested nvlist list should be checked using -.Fn nvlist_flags -function. -The given nvlist is always destroyed. +argument applies to the new nvlist similar to +.Fn nvlist_recv . +The nvlist +.Fa nvl +is always destroyed. +This function returns the new nvlist on success or +.Dv NULL +in case of an error. .Pp The .Fn nvlist_next -function iterates over the given nvlist returning names and types of subsequent +function iterates over +.Fa nvl +returning the names and types of subsequent elements. The .Fa cookiep -argument allows the function to figure out which element should be returned -next. -The +argument determines which element is returned. +If .Va *cookiep -should be set to -.Dv NULL -for the first call and should not be changed later. -Returning +is +.Dv NULL , +the values for the first element in the list are returned. +Otherwise, +.Va *cookiep +should contain the result of a prior call to +.Fn nvlist_next +in which case values for the next element from +.Fa nvl +are returned. +This function returns .Dv NULL -means there are no more elements on the nvlist. +when there are no more elements on +.Fa nvl . The .Fa typep -argument can be NULL. -Elements may not be removed from the nvlist while traversing it. -The nvlist must not be in error state. -Note that -.Fn nvlist_next -will handle -.Va cookiep -being set to +argument can be .Dv NULL . -In this case first element is returned or -.Dv NULL -if nvlist is empty. -This behavior simplifies removing the first element from the list. +Elements may not be removed from +.Fa nvl +the nvlist while traversing it. +.Fa nvl +must not be in the error state. +Additional actions can be performed on an element identified by a cookie +via the +.Xr cnv 9 +API . .Pp The .Fn nvlist_exists function returns .Dv true -if element of the given name exists (besides of its type) or +if an element named +.Fa name +exists in +.Fa nvl +(regardless of type) or .Dv false otherwise. -The nvlist must not be in error state. +The nvlist must not be in the error state. .Pp The .Fn nvlist_exists_type function returns .Dv true -if element of the given name and the given type exists or +if an element named +.Fa name +of type +.Fa type +exists or .Dv false otherwise. -The nvlist must not be in error state. +The nvlist must not be in the error state. .Pp The .Fn nvlist_exists_null , @@ -565,11 +599,13 @@ The .Fn nvlist_exists_descriptor_array functions return .Dv true -if element of the given name and the given type determined by the function name +if element named +.Fa name +with the type determined by the function name exists or .Dv false otherwise. -The nvlist must not be in error state. +The nvlist must not be in the error state. .Pp The .Fn nvlist_add_null , @@ -586,18 +622,23 @@ The .Fn nvlist_add_string_array , .Fn nvlist_add_nvlist_array , .Fn nvlist_add_descriptor_array -functions add element to the given nvlist. -When adding string or binary buffer the functions will allocate memory -and copy the data over. -When adding nvlist, the nvlist will be cloned and clone will be added. -When adding descriptor, the descriptor will be duplicated using the +functions add an element to +.Fa nvl . +When adding a string or binary buffer, these functions allocate memory +and copy the data. +When adding an nvlist, the +.Fa value +nvlist is cloned and the clone is added to +.Fa nvl . +When adding a file descriptor, the descriptor is duplicated via the .Xr dup 2 -system call and the new descriptor will be added. -The array functions will fail if there are any +system call and the new file descriptor is added. +The array functions fail if there are any .Dv NULL elements in the array, or if the array pointer is .Dv NULL . -If an error occurs while adding new element, internal error is set which can be +If an error occurs while adding a new element, +an internal error is set which can be examined using the .Fn nvlist_error function. @@ -612,17 +653,27 @@ The .Fn nvlist_move_string_array , .Fn nvlist_move_nvlist_array , .Fn nvlist_move_descriptor_array -functions add new element to the given nvlist, but unlike +functions add an element to +.Fa nvl , +but unlike the .Fn nvlist_add_<type> -functions they will consume the given resource. -In the case of strings, descriptors, or nvlists every elements must be -unique, or it could cause a double free. -The array functions will fail if there are any +functions they consume the given resource. +For string, file descriptor, binary buffer, or nvlist values, +no value should be moved into an nvlist multiple times; +doing so will cause that value to be freed multiple times. +Note that strings or binary buffers must be allocated with +.Xr malloc 3 , +and the pointers will be released via +.Xr free 3 +when +.Fa nvl +is destroyed. +The array functions fail if there are any .Dv NULL elements, or if the array pointer is .Dv NULL . If an error occurs while adding new element, the resource is destroyed and -internal error is set which can be examined using the +an internal error is set which can be examined using the .Fn nvlist_error function. .Pp @@ -638,37 +689,61 @@ The .Fn nvlist_get_string_array , .Fn nvlist_get_nvlist_array , .Fn nvlist_get_descriptor_array -functions return the value that corresponds to the given key name. -In the case of strings, nvlists, descriptors, binary, or arrays, the returned -resource should not be modified - they still belong to the nvlist. -If an element of the given name does not exist, the program will be aborted. -To avoid this, the caller should check for the existence of the name before -trying to obtain the value, or use the -.Xr dnvlist 3 -extension, which can provide a default value in the case of a missing element. -The nvlist must not be in error state. +functions return the value of the first element in +.Fa nvl +named +.Fa name . +For string, nvlist, file descriptor, binary buffer, or array values, +the returned resource must not be modified - it still belongs to +.Fa nvl . +.Pp +If an element named +.Fa name +does not exist, the program aborts. +To avoid this, the caller should check for the existence of the element before +trying to obtain the value or use the +.Xr dnv 9 +extension which provides a default value in the case of a missing element. +.Pp +The nvlist must not be in the error state. .Pp The .Fn nvlist_get_parent -function returns the parent nvlist of the nested nvlist. +function returns the parent nvlist of +.Fa nvl . .Pp The .Fn nvlist_get_array_next -function returns the next element from the array or -.Dv NULL -if the nvlist is not in array or it is the last element. -Note that -.Fn nvlist_get_array_next -only works if you added the nvlist array using the -.Fn nvlist_move_nvlist_array +function returns the next element after +.Fa nvl +from an array of nvlists. +If +.Fa nvl +is not in an array of nvlists or it is the last element, +this function returns +.Dv NULL . +An nvlist is only in an nvlist array if it was added to an nvlist array using +.Fn nvlist_add_nvlist_array , +.Fn nvlist_append_nvlist_array , or -.Fn nvlist_add_nvlist_array -functions. +.Fn nvlist_move_nvlist_array . .Pp The .Fn nvlist_get_pararr -function returns the next element in the array, or if not available -the parent of the nested nvlist. +function returns the next element after +.Fn nvl +from an array of nvlists. +If +.Fn nvl +is the last element in an array of nvlists, +the parent nvlist of +.Fa nvl is +returned. +If +.Fn nvl +is not in an array of nvlists, +.Dv NULL +is returned. .Pp The .Fn nvlist_take_bool , @@ -682,42 +757,38 @@ The .Fn nvlist_take_string_array , .Fn nvlist_take_nvlist_array , .Fn nvlist_take_descriptor_array -functions return value associated with the given name and remove the element -from the nvlist. -In case of string and binary values, the caller is responsible for free returned -memory using the +functions return the value of the element named +.Fa name +and remove the element from +.Fa nvl . +For string and binary buffer values, the caller is responsible for freeing +the returned value using the .Xr free 3 function. -In case of nvlist, the caller is responsible for destroying returned nvlist +For nvlist values, the caller is responsible for destroying the returned nvlist using the .Fn nvlist_destroy function. -In case of descriptor, the caller is responsible for closing returned descriptor +For file descriptor values, the caller is responsible for closing the +returned descriptor using the .Fn close 2 system call. -If an element of the given name does not exist, the program will be aborted. -To avoid that the caller should check for the existence of the given name -before trying to obtain the value, or use the -.Xr dnvlist 3 -extension, which can provide a default value in the case of a missing element. -In the case of an array of strings or binary values, the caller is responsible -for freeing every element of the array using the +For array values, the caller is responsible for destroying every element of +the array based on the element type. +In addition, the caller must also free the pointer to the array using the .Xr free 3 function. -In the case of an array of nvlists, the caller is responsible for destroying -every element of array using the -.Fn nvlist_destroy -function. -In the case of descriptors, the caller is responsible for closing every -element of array using the -.Fn close 2 -system call. -In every case involving an array, the caller must also free the pointer to -the array using the -.Xr free 3 -function. -The nvlist must not be in error state. +.Pp +If an element named +.Fa name +does not exist, the program aborts. +To avoid this, the caller should check for the existence of the element before +trying to obtain the value or use the +.Xr dnv 9 +extension which provides a default value in the case of a missing element. +.Pp +The nvlist must not be in the error state. .Pp The .Fn nvlist_append_bool_array , @@ -725,28 +796,46 @@ The .Fn nvlist_append_string_array , .Fn nvlist_append_nvlist_array , .Fn nvlist_append_descriptor_array -functions append an element to the existing array using the same semantics -as the add functions (i.e. the element will be copied when applicable). -If the array for a given key does not exist, then it will be created +functions append an element to an existing array using the same semantics +as the add functions (that is, the element will be copied when applicable). +If the array named +.Fa name +does not exist, then it will be created as if using the .Fn nvlist_add_<type>_array function. -The internal error is set on append failure. +If an error occurs while appending a new element, +an internal error is set on +.Fa nvl . .Pp The .Fn nvlist_free -function removes element of the given name from the nvlist (besides of its type) +function removes the first element named +.Fa name +from +.Fa nvl +(regardless of type) and frees all resources associated with it. -If element of the given name does not exist, the program will be aborted. -The nvlist must not be in error state. +If no element named +.Fa name +exists, the program aborts. +The nvlist must not be in the error state. .Pp The .Fn nvlist_free_type -function removes element of the given name and the given type from the nvlist +function removes the first element named +.Fa name +of type +.Fa type +from +.Fa nvl and frees all resources associated with it. -If element of the given name and the given type does not exist, the program -will be aborted. -The nvlist must not be in error state. +If no element named +.Fa name +of type +.Fa type +exists, the program aborts. +The nvlist must not be in the error state. .Pp The .Fn nvlist_free_null , @@ -761,20 +850,61 @@ The .Fn nvlist_free_string_array , .Fn nvlist_free_nvlist_array , .Fn nvlist_free_descriptor_array -functions remove element of the given name and the given type determined by the -function name from the nvlist and free all resources associated with it. -If element of the given name and the given type does not exist, the program -will be aborted. -The nvlist must not be in error state. -.Sh NOTES +functions remove the first element named +.Fa name +with the type determined by the function name from +.Fa nvl +free all resources associated with it. +If no element named +.Fa name +with the appropriate type exists, the program aborts. +The nvlist must not be in the error state. +.Ss Notes The .Fn nvlist_pack and .Fn nvlist_unpack -functions handle the byte-order conversions, so the binary buffer can be -packed/unpacked by the hosts with the different endianness. +functions handle byte-order conversions, so binary buffers can be +packed and unpacked on hosts with different endianness. +.Pp +The +.Fn nvlist_recv , +.Fn nvlist_send , +and +.Fn nvlist_xfer +functions can transfer nvlists between hosts with different endianness. +.Ss Kernel Considerations +The +.Nm nv , +.Nm cnv , +and +.Nm dnv +APIs can be used in the kernel with the following differences: +.Bl -bullet +.It +File descriptor and file descriptor array value types are not supported. +.It +.Fn nvlist_recv , +.Fn nvlist_send , +and +.Fn nvlist_xfer +are not supported. +.It +All memory allocations use the +.Dv M_NVLIST +memory type with +.Xr malloc 9 +and +.Xr free 9 . +As a result, any allocated buffers moved into an nvlist must be allocated with +.Dv M_NVLIST , +and buffers returned by functions such as +.Fn nvlist_pack +must be freed with +.Dv M_NVLIST . +.El .Sh EXAMPLES -The following example demonstrates how to prepare an nvlist and send it over +The following example demonstrates how to prepare an nvlist and send it over a .Xr unix 4 domain socket. .Bd -literal @@ -786,16 +916,18 @@ if (fd < 0) err(1, "open(\\"/tmp/foo\\") failed"); nvl = nvlist_create(0); + /* - * There is no need to check if nvlist_create() succeeded, + * There is no need to check if nvlist_create() succeeded * as the nvlist_add_<type>() functions can cope. * If it failed, nvlist_send() will fail. */ nvlist_add_string(nvl, "filename", "/tmp/foo"); nvlist_add_number(nvl, "flags", O_RDONLY); + /* * We just want to send the descriptor, so we can give it - * for the nvlist to consume (that's why we use nvlist_move + * for the nvlist to consume (that is why we use nvlist_move * not nvlist_add). */ nvlist_move_descriptor(nvl, "fd", fd); @@ -806,7 +938,7 @@ if (nvlist_send(sock, nvl) < 0) { nvlist_destroy(nvl); .Ed .Pp -Receiving nvlist and getting data: +Receiving an nvlist and retrieving element values: .Bd -literal nvlist_t *nvl; const char *command; @@ -817,25 +949,27 @@ nvl = nvlist_recv(sock, 0); if (nvl == NULL) err(1, "nvlist_recv() failed"); -/* For command we take pointer to nvlist's buffer. */ +/* For command we accept a pointer to the nvlist's internal buffer. */ command = nvlist_get_string(nvl, "command"); + /* * For filename we remove it from the nvlist and take * ownership of the buffer. */ filename = nvlist_take_string(nvl, "filename"); -/* The same for the descriptor. */ + +/* The same for the file descriptor. */ fd = nvlist_take_descriptor(nvl, "fd"); printf("command=%s filename=%s fd=%d\n", command, filename, fd); +/* command is freed by nvlist_destroy() */ nvlist_destroy(nvl); free(filename); close(fd); -/* command was freed by nvlist_destroy() */ .Ed .Pp -Iterating over nvlist: +Iterating over an nvlist: .Bd -literal nvlist_t *nvl; const char *name; @@ -898,7 +1032,7 @@ nvl = nvlist_recv(sock, 0); if (nvl == null) err(1, "nvlist_recv() failed"); -cookie = null; +cookie = NULL; do { while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { if (type == NV_TYPE_NVLIST) { diff --git a/share/man/man9/osd.9 b/share/man/man9/osd.9 index 82f279ef17f4..5e0e482914c3 100644 --- a/share/man/man9/osd.9 +++ b/share/man/man9/osd.9 @@ -23,7 +23,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd April 26, 2016 +.Dd October 07, 2024 .Dt OSD 9 .Os .Sh NAME @@ -49,7 +49,7 @@ .Fo osd_register .Fa "u_int type" .Fa "osd_destructor_t destructor" -.Fa "osd_method_t *methods" +.Fa "const osd_method_t *methods" .Fc .Ft void .Fo osd_deregister @@ -396,7 +396,7 @@ API. .Pp .Fn osd_get only acquires an -.Xr rmlock +.Xr rmlock 9 in read mode, therefore making it safe to use in the majority of contexts within the kernel including most fast paths. .Sh RETURN VALUES diff --git a/share/man/man9/p_candebug.9 b/share/man/man9/p_candebug.9 index c824db974154..be4710f0a15f 100644 --- a/share/man/man9/p_candebug.9 +++ b/share/man/man9/p_candebug.9 @@ -138,8 +138,8 @@ command .Pc . .El .Sh SEE ALSO -.Xr prison_check 9 , -.Xr mac 9 , -.Xr cr_bsd_visible 9 , .Xr procctl 2 , -.Xr p_cansee 9 +.Xr cr_bsd_visible 9 , +.Xr mac 9 , +.Xr p_cansee 9 , +.Xr prison_check 9 diff --git a/share/man/man9/p_cansee.9 b/share/man/man9/p_cansee.9 index 9fdce460dfea..7de0c9654995 100644 --- a/share/man/man9/p_cansee.9 +++ b/share/man/man9/p_cansee.9 @@ -74,6 +74,6 @@ and cannot see it as determined by .Xr cr_cansee 9 . .El .Sh SEE ALSO -.Xr ucred 9 , .Xr cr_cansee 9 , -.Xr p_candebug 9 +.Xr p_candebug 9 , +.Xr ucred 9 diff --git a/share/man/man9/pci.9 b/share/man/man9/pci.9 index 3c3e54bf8760..8f772e76ba99 100644 --- a/share/man/man9/pci.9 +++ b/share/man/man9/pci.9 @@ -23,17 +23,19 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd May 20, 2021 +.Dd March 27, 2025 .Dt PCI 9 .Os .Sh NAME .Nm pci , .Nm pci_alloc_msi , .Nm pci_alloc_msix , +.Nm pci_clear_pme , .Nm pci_disable_busmaster , .Nm pci_disable_io , .Nm pci_enable_busmaster , .Nm pci_enable_io , +.Nm pci_enable_pme , .Nm pci_find_bsf , .Nm pci_find_cap , .Nm pci_find_dbsf , @@ -50,6 +52,7 @@ .Nm pci_get_powerstate , .Nm pci_get_vpd_ident , .Nm pci_get_vpd_readonly , +.Nm pci_has_pm , .Nm pci_iov_attach , .Nm pci_iov_attach_name , .Nm pci_iov_detach , @@ -81,6 +84,8 @@ .Fn pci_alloc_msi "device_t dev" "int *count" .Ft int .Fn pci_alloc_msix "device_t dev" "int *count" +.Ft void +.Fn pci_clear_pme "device_t dev" .Ft int .Fn pci_disable_busmaster "device_t dev" .Ft int @@ -89,6 +94,8 @@ .Fn pci_enable_busmaster "device_t dev" .Ft int .Fn pci_enable_io "device_t dev" "int space" +.Ft void +.Fn pci_enable_pme "device_t dev" .Ft device_t .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func" .Ft int @@ -121,6 +128,8 @@ .Fn pci_get_vpd_ident "device_t dev" "const char **identptr" .Ft int .Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr" +.Ft bool +.Fn pci_has_pm "device_t dev" .Ft int .Fn pci_msi_count "device_t dev" .Ft int @@ -355,6 +364,12 @@ When no more instances are located returns an error. .Pp The +.Fn pci_has_pm +function returns true if +.Fa dev +supports power management. +.Pp +The .Fn pci_find_extcap function is used to locate the first instance of a PCI-express extended capability register set for the device @@ -670,6 +685,16 @@ then the function will fail with .Er EOPNOTSUPP . .Pp The +.Fn pci_clear_pme +function is used to clear any pending PME# signal and disable generation +of power management events. +.Pp +The +.Fn pci_enable_pme +function is used to enable generation of power management events before +suspending a device. +.Pp +The .Fn pci_iov_attach function is used to advertise that the given device .Pq and associated device driver diff --git a/share/man/man9/pci_iov_schema.9 b/share/man/man9/pci_iov_schema.9 index 764d357fbaee..99589b59fb91 100644 --- a/share/man/man9/pci_iov_schema.9 +++ b/share/man/man9/pci_iov_schema.9 @@ -38,7 +38,7 @@ .Nm pci_iov_schema_add_unicast_mac .Nd PCI SR-IOV config schema interface .Sh SYNOPSIS -.In machine/stdarg.h +.In sys/stdarg.h .In sys/nv.h .In sys/iov_schema.h .Ft nvlist_t * diff --git a/share/man/man9/pfind.9 b/share/man/man9/pfind.9 index 48e34d65d6ab..ebcf7a565150 100644 --- a/share/man/man9/pfind.9 +++ b/share/man/man9/pfind.9 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd July 11, 2001 +.Dd December 3, 2024 .Dt PFIND 9 .Os .Sh NAME @@ -34,7 +34,9 @@ .Ft "struct proc *" .Fn pfind "pid_t pid" .Ft "struct proc *" -.Fn zpfind "pid_t pid" +.Fn pfind_any "pid_t pid" +.Ft "struct proc *" +.Fn pfind_any_locked "pid_t pid" .Sh DESCRIPTION .Fn pfind takes a @@ -47,36 +49,39 @@ is on the .Va allproc list. .Pp -.Fn zpfind +.Fn pfind_any takes a .Fa pid as its argument. -If -.Fn zpfind -finds a process whose PID is equal to that of argument -and is a zombie process, meaning that it must reside on the -.Va zombproc -list, -.Fn zpfind -returns a pointer to that -.Vt proc -structure. +.Fn pfind_any +searches the +.Va allproc +list and returns the first process whose PID matches and whose state is +.Va PRS_ZOMBIE . .Pp -Both -.Fn pfind +.Fn pfind_any_locked +is similar to +.Fn pfind_any +,but it does not lock the process hash bucket +for the given +.Vt pid . +Instead, it asserts the corresponding process hash bucket is already locked. +All three functions +.Fn pfind , +.Fn pfind_any , and -.Fn zpfind +.Fn pgfind_any_locked lock the .Vt proc -structure that is returned using -.Fn PROC_LOCK "p" . +structure before returning. .Sh RETURN VALUES -.Fn pfind +.Fn pfind , +.Fn pfind_any , and -.Fn zpfind -return a pointer to a +.Fn pfind_any_locked +return pointer to a .Vt proc -structure on success and a +structure on success or .Dv NULL on failure. .Sh SEE ALSO diff --git a/share/man/man9/pseudofs.9 b/share/man/man9/pseudofs.9 index e076c398c711..d87bbb0030c7 100644 --- a/share/man/man9/pseudofs.9 +++ b/share/man/man9/pseudofs.9 @@ -36,9 +36,9 @@ The .Nm module offers an abstract API for pseudo-file systems such as -.Xr procfs 5 +.Xr procfs 4 and -.Xr linprocfs 5 . +.Xr linprocfs 4 . It takes care of all the hairy bits like interfacing with the VFS system, enforcing access control, keeping track of file numbers, and cloning files and directories that are process-specific. @@ -51,9 +51,9 @@ and callbacks that report file attributes or write the actual file contents into sbufs. .\" Insert more info here .Sh SEE ALSO -.Xr linprocfs 5 , -.Xr linsysfs 5 , -.Xr procfs 5 , +.Xr linprocfs 4 , +.Xr linsysfs 4 , +.Xr procfs 4 , .Xr sbuf 9 , .Xr vnode 9 .Sh HISTORY diff --git a/share/man/man9/random.9 b/share/man/man9/random.9 index 7fc721564897..f1833c63a2ff 100644 --- a/share/man/man9/random.9 +++ b/share/man/man9/random.9 @@ -24,7 +24,7 @@ .\" (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 March 18, 2024 +.Dd May 11, 2025 .Dt RANDOM 9 .Os .Sh NAME @@ -133,7 +133,7 @@ The deprecated .Fn random function will return a 31-bit value. It is obsolete and scheduled to be removed in -.Fx 15.0 . +.Fx 16.0 . Consider .Xr prng 9 instead and see diff --git a/share/man/man9/refcount.9 b/share/man/man9/refcount.9 index 0c8e4380aed3..78631f9a865a 100644 --- a/share/man/man9/refcount.9 +++ b/share/man/man9/refcount.9 @@ -3,7 +3,7 @@ .\" Written by: John H. Baldwin <jhb@FreeBSD.org> .\" All rights reserved. .\" -.\" Copyright (c) 2019 The FreeBSD Foundation, Inc. +.\" Copyright (c) 2019 The FreeBSD Foundation .\" .\" Parts of this documentation was written by .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship diff --git a/share/man/man9/rman.9 b/share/man/man9/rman.9 index 35a2d176233c..d175b60b4010 100644 --- a/share/man/man9/rman.9 +++ b/share/man/man9/rman.9 @@ -40,7 +40,6 @@ .Nm rman_last_free_region , .Nm rman_release_resource , .Nm rman_reserve_resource , -.Nm rman_reserve_resource_bound , .Nm rman_make_alignment_flags , .Nm rman_get_start , .Nm rman_get_end , @@ -90,11 +89,6 @@ .Fa "struct rman *rm" "rman_res_t start" "rman_res_t end" "rman_res_t count" .Fa "u_int flags" "device_t dev" .Fc -.Ft "struct resource *" -.Fo rman_reserve_resource_bound -.Fa "struct rman *rm" "rman_res_t start" "rman_res_t end" "rman_res_t count" -.Fa "rman_res_t bound" "u_int flags" "device_t dev" -.Fc .Ft uint32_t .Fn rman_make_alignment_flags "uint32_t size" .Ft rman_res_t @@ -266,7 +260,7 @@ and are set to the bounds of the free region and zero is returned. .Pp The -.Fn rman_reserve_resource_bound +.Fn rman_reserve_resource function is where the bulk of the .Nm logic is located. @@ -279,7 +273,7 @@ The caller can specify the and .Fa end of an acceptable range, -as well as a boundary restriction and required alignment, +required alignment, and the code will attempt to find a free segment which fits. The .Fa start @@ -296,15 +290,13 @@ The alignment requirement .Pq if any is specified in .Fa flags . -The -.Fa bound -argument may be set to specify a boundary restriction such that an -allocated region may cross an address that is a multiple of the -boundary. -The -.Fa bound -argument must be a power of two. -It may be set to zero to specify no boundary restriction. +Often the +.Dv RF_ALIGNMENT_LOG2 +macro is used to specify alignment to a power-of-2 size, or +.Fn rman_make_alignment_flags +can be used to compute the +.Fa flags +value at runtime. A shared segment will be allocated if the .Dv RF_SHAREABLE flag is set, otherwise an exclusive segment will be allocated. @@ -312,15 +304,6 @@ If this shared segment already exists, the caller has its device added to the list of consumers. .Pp The -.Fn rman_reserve_resource -function is used to reserve resources within a previously established region. -It is a simplified interface to -.Fn rman_reserve_resource_bound -which passes 0 for the -.Fa bound -argument. -.Pp -The .Fn rman_make_alignment_flags function returns the flag mask corresponding to the desired alignment .Fa size . diff --git a/share/man/man9/rtentry.9 b/share/man/man9/rtentry.9 index f9d2b1668da5..3f2e6c9ef656 100644 --- a/share/man/man9/rtentry.9 +++ b/share/man/man9/rtentry.9 @@ -227,7 +227,7 @@ Empty space available for protocol-specific information. .El .Sh SEE ALSO .Xr route 4 , -.Xr route 8 , +.Xr route 8 .Sh HISTORY The .Vt rtentry diff --git a/share/man/man9/sglist.9 b/share/man/man9/sglist.9 index 49d0cbfd1871..f4930134e7cf 100644 --- a/share/man/man9/sglist.9 +++ b/share/man/man9/sglist.9 @@ -285,7 +285,7 @@ to the scatter/gather list .Fa sg . .Pp The -.Nm sglist_append_mbuf +.Nm sglist_append_single_mbuf function appends the physical address ranges described by a single mbuf .Fa m to the scatter/gather list diff --git a/share/man/man9/style.9 b/share/man/man9/style.9 index 8eb82e3419ec..e9f17392ae0c 100644 --- a/share/man/man9/style.9 +++ b/share/man/man9/style.9 @@ -1,5 +1,5 @@ -.\"- -.\" Copyright (c) 1995-2022 The FreeBSD Project +.\" +.\" Copyright (c) 1995-2025 The FreeBSD Project .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -22,12 +22,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd April 26, 2024 +.Dd July 28, 2025 .Dt STYLE 9 .Os .Sh NAME .Nm style -.Nd "kernel source file style guide" +.Nd kernel source file style guide .Sh DESCRIPTION This file specifies the preferred style for kernel source files in the .Fx @@ -52,35 +52,31 @@ is silent on an issue. /* Most single-line comments look like this. */ +// Although they may look like this. + /* * Multi-line comments look like this. Make them real sentences. Fill * them so they look like real paragraphs. */ .Ed .Pp -The copyright header should be a multi-line comment, with the first -line of the comment having a dash after the star like so: +C++ comments may be used in C and C++ code. +Single-line comments should be consistently either C or C++ within a file. +Multi-line comments should also be consistently either C or C++, but may differ +from single-line comments. +.Pp +The copyright header should be a multi-line comment like so: .Bd -literal -/*- - * SPDX-License-Identifier: BSD-2-Clause - * +/* * Copyright (c) 1984-2025 John Q. Public * - * Long, boring license goes here, but trimmed for brevity + * SPDX-License-Identifier: BSD-2-Clause */ .Ed .Pp -An automatic script collects license information from the tree for -all comments that start in the first column with -.Dq Li "/*-" . -If you desire to flag -.Xr indent 1 -to not reformat a comment that starts in the first column which is not a -license or copyright notice, change the dash to a star for those -comments. Comments starting in columns other than the first are never considered license statements. -Use the appropriate SPDX-License-Identifier line before the copyright. +Write the copyright lines before the appropriate SPDX-License-Identifier. If the copyright assertion contains the phrase .Dq Li "All Rights Reserved" that should be on the same line as the word @@ -126,22 +122,17 @@ Only add in front of foreign VCS IDs if the file is renamed. Add .Dq Li "From: " -and FreeBSD git hash with full path name if the file was derived -from another FreeBSD file and include relevant copyright info -from the original file. -.Bd -literal -.Ed +and the +.Fx +git hash with full path name if the file was derived from another +.Fx +file and include relevant copyright info from the original file. .Pp Leave one blank line before the header files. .Pp Kernel include files .Pa ( sys/*.h ) come first. -If -.In sys/cdefs.h -is needed for -.Fn __FBSDID , -include it first. If either .In sys/types.h or @@ -519,7 +510,7 @@ parts of the cascade. Elements in a .Ic switch -statement that cascade should have a +statement that execute some code and then cascade to the next case should have a .Li FALLTHROUGH comment. Numerical arguments should be checked for accuracy. @@ -745,9 +736,10 @@ not: !(p = f()) .Ed .Pp -Do not use +Do not test without a comparison, or with unary .Ic \&! -for tests unless it is a boolean, e.g., use: +(except for booleans). +For example, use: .Bd -literal if (*p == '\e0') .Ed @@ -757,6 +749,16 @@ not: if (!*p) .Ed .Pp +Prefer: +.Bd -literal +if (count != 0) +.Ed +.Pp +over: +.Bd -literal +if (count) +.Ed +.Pp Routines returning .Vt "void *" should not have their return values cast @@ -806,19 +808,15 @@ vaf(const char *fmt, ...) static void usage(void) { - /* Optional blank line goes here. */ .Ed .Pp -Optionally, insert a blank line at the beginning of functions with no local -variables. +Functions should have local variable declarations first, followed by one +blank line, followed by the first statement. +If no local variables are declared, the first line should be a statement. Older versions of this .Nm -document required the blank line convention, so it is widely used in existing -code. -.Pp -Do not insert a blank line at the beginning of functions with local variables. -Instead, these should have local variable declarations first, followed by one -blank line, followed by the first statement. +document required a blank line before code. +Such lines should be removed when signficant changes are made to the code. .Pp Use .Xr printf 3 , @@ -902,6 +900,178 @@ New code should use .Fn _Static_assert instead of the older .Fn CTASSERT . +.Pp +.Fn __predict_true +and +.Fn __predict_false +should only be used in frequently executed code when it makes the code +measurably faster. +It is wasteful to make predictions for infrequently run code, like subsystem +initialization. +When using branch prediction hints, atypical error conditions should use +.Fn __predict_false +(document the exceptions). +Operations that almost always succeed use +.Fn __predict_true . +Only use the annotation for the entire if statement, +rather than individual clauses. +Do not add these annotations without empirical evidence of the likelihood of the +branch. +.Ss C++ +KNF style was originally defined as a style for C. +C++ introduces several new idioms which do not have an existing corollary +in KNF C such as inline function definitions in classes. +C++ is also not always compatible with some KNF guidelines such as +enclosing return values in parentheses. +For C++ code, FreeBSD aims to follow broadly accepted C++ practices while +also following the general shape of KNF. +This section enumerates C++ specific guidelines that differ from KNF C. +.Pp +The preferred suffixes for C++ source files are +.Dq .cc +and +.Dq .hh . +Header files should always use a suffix, +unlike headers from the C++ standard library. +.Pp +Return values should not be enclosed in parantheses. +When converting existing C code to C++, +existing return values may remain in parantheses. +.Pp +The opening curly brace for namespace declarations should be on the first line +similar to structure and class definitions. +Nested namespaces should be declared using a single namespace declaration. +.Bd -literal +namespace foo::bar { +} +.Ed +.Pp +Member function declarations should follow the same style used for standalone +function protoypes except that a space should be used between a function's +return type and name. +.Pp +Function definitions at the top level should use a newline after the function +type similar to C function definitions. +.Pp +Nested member function definitions inside of a class, structure, or union +should not use a newline after the function type. +Instead, these should follow the style of member function declarations. +This is more common C++ style and is more compact for small methods such as +getters and setters. +.Pp +Inline functions whose body consists of a single statement may use a single +line for the function body. +Inline functions with an empty body should always use a single line. +.Bd -literal +struct widget { + int foo() { return 4; } + int bar(); +}; + +int +widget::bar() +{ + return 6; +} +.Ed +.Pp +Default and deleted methods should be declared as a single line. +.Bd -literal +class box { + ~box() = default; +}; +.Ed +.Pp +In template declarations, the +.Ic template +keyword and list of template parameters should be followed by a newline +before the templated declaration. +.Bd -literal +template <typename T> +class box { + T data; +}; +.Ed +.Pp +The +.Ic & +for reference variables should be placed on the variable name rather +than the type similar to the style used with +.Ic * +for pointers. +.Bd -literal + int x; + int &xp = x; +.Ed +.Pp +Variables may be declared at any point within a function, +not just at the start of blocks. +.Pp +Standard library containers should be used in preference to +.Xr queue 3 +or +.Xr tree 3 +macros. +.Pp +.Ic nullptr +should be used instead of +.Dv NULL +or 0. +.Pp +Use standard library types for managing strings such as +.Vt std::string +and +.Vt std::string_view +rather than +.Vt "char *" +and +.Vt "const char *" . +C types may be used when interfacing with C code. +.Pp +The +.Ic auto +keyword can be used in various contexts which improve readability. +Examples include iterators, non-trivial types of ranged-for values, +and return values of obvious types, +such as +.Ic static_cast +or +.Fn std::make_unique . +Place any qualifiers before +.Ic auto , +for example: +.Ic const auto . +.Pp +Use the +.Vt std::unique_ptr +and +.Vt std::shared_ptr +smart pointers to manage the lifetime of dynamically allocated objects +instead of +.Ic new +and +.Ic delete . +Construct smart pointers with +.Fn std::make_unique +or +.Fn std::make_shared . +Do not use +.Xr malloc 3 +except when necessary to interface with C code. +.Pp +Do not import any namespaces with +.Ic using +at global scope in header files. +Namespaces other than the +.Ic std +namespace (for example, +.Ic std::literals ) +may be imported in source files and in function scope in header files. +.Pp +Define type aliases using +.Ic using +instead of +.Ic typedef . .Sh FILES .Bl -tag -width indent .It Pa /usr/src/tools/build/checkstyle9.pl diff --git a/share/man/man9/sysctl.9 b/share/man/man9/sysctl.9 index 8c4ee71c96c6..92c8532c8ed2 100644 --- a/share/man/man9/sysctl.9 +++ b/share/man/man9/sysctl.9 @@ -931,8 +931,8 @@ Examples of integer, opaque, string, and procedure sysctls follow: * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR, * and the value is declared. */ -SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR, - sizeof(struct bio), "sizeof(struct bio)"); +SYSCTL_INT(_kern, OID_AUTO, hz_max, CTLFLAG_RD, SYSCTL_NULL_INT_PTR, HZ_MAXIMUM, + "Maximum hz value supported"); /* * Example of a variable integer value. Notice that the control diff --git a/share/man/man9/tcp_functions.9 b/share/man/man9/tcp_functions.9 index eb9b299eae9e..8ba7f21c978c 100644 --- a/share/man/man9/tcp_functions.9 +++ b/share/man/man9/tcp_functions.9 @@ -23,7 +23,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd March 10, 2017 +.Dd July 13, 2024 .Dt TCP_FUNCTIONS 9 .Os .Sh NAME @@ -37,6 +37,7 @@ .Ft int .Fn register_tcp_functions_as_name "struct tcp_function_block *blk" \ "const char *name" "int wait" +.Ft int .Fn register_tcp_functions_as_names "struct tcp_function_block *blk" \ "int wait" "const char *names[]" "int *num_names" .Ft int @@ -112,6 +113,7 @@ argument. The .Fa num_names argument provides a pointer to the number of names. +This number must not exceed TCP_FUNCTION_NAME_NUM_MAX. This function will either succeed in registering all of the names in the array, or none of the names in the array. On failure, the @@ -176,9 +178,10 @@ struct tcp_function_block { uint32_t, u_int); int (*tfb_tcp_timer_active)(struct tcpcb *, uint32_t); void (*tfb_tcp_timer_stop)(struct tcpcb *, uint32_t); - /* Optional functions */ + /* Optional function */ void (*tfb_tcp_rexmit_tmr)(struct tcpcb *); - void (*tfb_tcp_handoff_ok)(struct tcpcb *); + /* Mandatory function */ + int (*tfb_tcp_handoff_ok)(struct tcpcb *); /* System use */ volatile uint32_t tfb_refcnt; uint32_t tfb_flags; @@ -261,37 +264,21 @@ However, care must be taken to ensure the retransmit timer leaves the TCP control block in a valid state for the remainder of the retransmit timer logic. .Pp -A user may select a new TCP stack before calling -.Xr connect 2 -or -.Xr listen 2 . -Optionally, a TCP stack may also allow a user to begin using the TCP stack for -a connection that is in a later state by setting a non-NULL function pointer in -the +A user may select a new TCP stack before calling at any time. +Therefore, the function pointer .Va tfb_tcp_handoff_ok -field. -If this field is non-NULL and a user attempts to select that TCP stack after -calling -.Xr connect 2 -or -.Xr listen 2 -for that socket, the kernel will call the function pointed to by the +field must be non-NULL. +If a user attempts to select that TCP stack, the kernel will call the function +pointed to by the .Va tfb_tcp_handoff_ok field. The function should return 0 if the user is allowed to switch the socket to use -the TCP stack. -Otherwise, the function should return an error code, which will be returned to -the user. -If the -.Va tfb_tcp_handoff_ok -field is -.Dv NULL -and a user attempts to select the TCP stack after calling -.Xr connect 2 -or -.Xr listen 2 -for that socket, the operation will fail and the kernel will return -.Er EINVAL . +the TCP stack. In this case, the kernel will call the function pointed to by +.Va tfb_tcp_fb_init +if this function pointer is non-NULL and finally perform the stack switch. +If the user is not allowed to switch the socket, the function should undo any +changes it made to the connection state configuration and return an error code, +which will be returned to the user. .Pp The .Va tfb_refcnt @@ -343,8 +330,11 @@ must be prepared to wait until all connections have stopped using the specified TCP stack. .Sh ERRORS The -.Fn register_tcp_functions -function will fail if: +.Fn register_tcp_functions , +.Fn register_tcp_functions_as_name , +and +.Fn register_tcp_functions_as_names +functions will fail if: .Bl -tag -width Er .It Bq Er EINVAL Any of the members of the @@ -353,7 +343,19 @@ argument are set incorrectly. .It Bq Er ENOMEM The function could not allocate memory for its internal data. .It Bq Er EALREADY -A function block is already registered with the same name. +The +.Fa blk +is already registered or a function block is already registered with the same +name. +.El +Additionally, +.Fn register_tcp_functions_as_names +will fail if: +.Bl -tag -width Er +.It Bq Er E2BIG +The number of names pointed to by the +.Fa num_names +argument is larger than TCP_FUNCTION_NAME_NUM_MAX. .El The .Fn deregister_tcp_functions diff --git a/share/man/man9/vfs_getopt.9 b/share/man/man9/vfs_getopt.9 index 0e68655f540f..ff0f027314c7 100644 --- a/share/man/man9/vfs_getopt.9 +++ b/share/man/man9/vfs_getopt.9 @@ -24,7 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" -.Dd July 31, 2011 +.Dd May 19, 2024 .Dt VFS_GETOPT 9 .Os .Sh NAME @@ -46,7 +46,7 @@ .Fa "struct vfsoptlist *opts" "const char *name" "void **buf" "int *len" .Fc .Ft "char *" -.Fn vfs_getops "struct vfsoptlist *opts" "const char *name" "int *error" +.Fn vfs_getopts "struct vfsoptlist *opts" "const char *name" "int *error" .Ft int .Fo vfs_flagopt .Fa "struct vfsoptlist *opts" "const char *name" "uint64_t *flags" "uint64_t flag" @@ -177,7 +177,7 @@ function returns 0 if the option was found; otherwise, is returned. .Pp The -.Fn vfs_getops +.Fn vfs_getopts function returns the specified option if it is found, and is .Dv NUL terminated. diff --git a/share/man/man9/vm_map.9 b/share/man/man9/vm_map.9 index 81379a5c347d..d08d54bd1004 100644 --- a/share/man/man9/vm_map.9 +++ b/share/man/man9/vm_map.9 @@ -49,15 +49,15 @@ subordinate maps, created using the function. .Bd -literal -offset indent struct vm_map { - struct vm_map_entry header; - struct sx lock; - struct mtx system_mtx; + struct vm_map_entry header; + union { + struct sx lock; + struct mtx system_mtx; + }; int nentries; vm_size_t size; u_int timestamp; - u_char needs_wakeup; - u_char system_map; - vm_flags_t flags; + u_int flags; vm_map_entry_t root; pmap_t pmap; int busy; @@ -83,12 +83,6 @@ A count of the members in use within the circular map entry list. Specifies the size of the virtual address space. .It Va timestamp Used to determine if the map has changed since its last access. -.It Va needs_wakeup -Indicates if a thread is waiting for an allocation within the map. -Used only by system maps. -.It Va system_map -Set to TRUE to indicate that map is a system map; otherwise, it belongs -to a user process. .It Va flags Map flags, described below. .It Va root @@ -106,6 +100,12 @@ Possible map flags: Wire all future pages in this map. .It Dv MAP_BUSY_WAKEUP There are waiters for the map busy status. +.It Va MAP_NEEDS_WAKEUP +Indicates if a thread is waiting for an allocation within the map. +Used only by system maps. +.It Va MAP_SYSTEM_MAP +If set, indicates that the map is the system map; otherwise, it belongs +to a user process. .El .Pp The following flags can be passed to @@ -323,7 +323,6 @@ is backed by a .Xr vm_map_pmap 9 , .Xr vm_map_protect 9 , .Xr vm_map_remove 9 , -.Xr vm_map_simplify_entry 9 , .Xr vm_map_stack 9 , .Xr vm_map_submap 9 , .Xr vm_map_sync 9 , diff --git a/share/man/man9/vm_map_protect.9 b/share/man/man9/vm_map_protect.9 index 21e7b53a6bc6..5ece889a85df 100644 --- a/share/man/man9/vm_map_protect.9 +++ b/share/man/man9/vm_map_protect.9 @@ -1,6 +1,6 @@ .\" .\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> -.\" Copyright (c) 2021 The FreeBSD Foundation, Inc. +.\" Copyright (c) 2021 The FreeBSD Foundation .\" All rights reserved. .\" .\" Parts of this documentation were written by diff --git a/share/man/man9/vm_map_simplify_entry.9 b/share/man/man9/vm_map_simplify_entry.9 deleted file mode 100644 index 0e99596d067e..000000000000 --- a/share/man/man9/vm_map_simplify_entry.9 +++ /dev/null @@ -1,59 +0,0 @@ -.\" -.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> -.\" 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 July 19, 2003 -.Dt VM_MAP_SIMPLIFY_ENTRY 9 -.Os -.Sh NAME -.Nm vm_map_simplify_entry -.Nd simplify a -.Vt vm_map_entry -.Sh SYNOPSIS -.In sys/param.h -.In vm/vm.h -.In vm/vm_map.h -.Ft void -.Fn vm_map_simplify_entry "vm_map_t map" "vm_map_entry_t entry" -.Sh DESCRIPTION -The -.Fn vm_map_simplify_entry -function simplifies the given -.Fa entry -by merging with either neighbour. -The -.Fa map -must be locked upon entry. -.Pp -This function also has the ability to merge with both neighbours. -.Pp -This function guarantees that the passed entry remains valid, although -possibly extended. -.Sh SEE ALSO -.Xr vm_map 9 , -.Xr vm_map_insert 9 , -.Xr vm_map_remove 9 -.Sh AUTHORS -This manual page was written by -.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/share/man/man9/vm_page_alloc.9 b/share/man/man9/vm_page_alloc.9 index de225e05d707..4bf8db33a28d 100644 --- a/share/man/man9/vm_page_alloc.9 +++ b/share/man/man9/vm_page_alloc.9 @@ -28,7 +28,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" -.Dd November 11, 2021 +.Dd August 4, 2024 .Dt VM_PAGE_ALLOC 9 .Os .Sh NAME @@ -87,17 +87,6 @@ .Fa "vm_page_t mpred" .Fc .Ft vm_page_t -.Fo vm_page_alloc_freelist -.Fa "int freelist" -.Fa "int req" -.Fc -.Ft vm_page_t -.Fo vm_page_alloc_freelist_domain -.Fa "int domain" -.Fa "int freelist" -.Fa "int req" -.Fc -.Ft vm_page_t .Fo vm_page_alloc_noobj .Fa "int req" .Fc @@ -212,19 +201,6 @@ or will carry the machine-dependent encoding of the memory attribute. Additionally, the direct mapping of the page, if any, will be updated to reflect the requested memory attribute. -.Pp -The -.Fn vm_page_alloc_freelist -and -.Fn vm_page_alloc_freelist_domain -functions behave identically to -.Fn vm_page_alloc_noobj -and -.Fn vm_page_alloc_noobj_domain , -respectively, except that a successful allocation will return a page from the -specified physical memory freelist. -These functions are not intended for use outside of the virtual memory -subsystem and exist only to support the requirements of certain platforms. .Sh REQUEST FLAGS All page allocator functions accept a .Fa req @@ -331,6 +307,10 @@ pages will be allocated by the caller in the near future. must be no larger than 65535. If the system is short of free pages, this hint may cause the kernel to reclaim memory more aggressively than it would otherwise. +.It Dv VM_ALLOC_NOFREE +The caller asserts that the returned page will never be released. +If this flag is specified, the allocator will try to fetch a page from a +special per-domain arena in order to curb long-term physical memory fragmentation. .El .Sh RETURN VALUES If the allocation was successful, a pointer to the diff --git a/share/man/man9/vmem.9 b/share/man/man9/vmem.9 index 1dc74e951cb2..053aec856a78 100644 --- a/share/man/man9/vmem.9 +++ b/share/man/man9/vmem.9 @@ -1,3 +1,6 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" .\" $NetBSD: vmem.9,v 1.15 2013/01/29 22:02:17 wiz Exp $ .\" .\" Copyright (c)2006 YAMAMOTO Takashi, @@ -74,7 +77,7 @@ other than virtual memory. .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - .Fn vmem_create creates a new vmem arena. -.Bl -tag -width qcache_max +.Bl -tag -offset indent -width "qcache_max" .It Fa name The string to describe the vmem. .It Fa base @@ -117,7 +120,7 @@ wait flag. .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - .Fn vmem_xalloc allocates a resource from the arena. -.Bl -tag -width nocross +.Bl -tag -offset indent -width "qcache_max" .It Fa vm The arena which we allocate from. .It Fa size @@ -159,7 +162,7 @@ A bitwise OR of an allocation strategy and a .Xr malloc 9 wait flag. The allocation strategy is one of: -.Bl -tag width indent +.Bl -tag -width "M_FIRSTFIT" .It Dv M_FIRSTFIT Prefer allocation performance. .It Dv M_BESTFIT @@ -182,7 +185,7 @@ overwrites it with the start address of the allocated span. frees resource allocated by .Fn vmem_xalloc to the arena. -.Bl -tag -width addr +.Bl -tag -offset indent -width "qcache_max" .It Fa vm The arena which we free to. .It Fa addr @@ -203,7 +206,7 @@ argument used for .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - .Fn vmem_alloc allocates a resource from the arena. -.Bl -tag -width flags +.Bl -tag -offset indent -width "qcache_max" .It Fa vm The arena which we allocate from. .It Fa size @@ -228,7 +231,7 @@ overwrites it with the start address of the allocated span. frees resource allocated by .Fn vmem_alloc to the arena. -.Bl -tag -width addr +.Bl -tag -offset indent -width "qcache_max" .It Fa vm The arena which we free to. .It Fa addr @@ -249,7 +252,7 @@ argument used for .\" ------------------------------------------------------------ .Fn vmem_destroy destroys a vmem arena. -.Bl -tag -width vm +.Bl -tag -offset indent -width "qcache_max" .It Fa vm The vmem arena being destroyed. The caller should ensure that no one will use it anymore. diff --git a/share/man/man9/vnode.9 b/share/man/man9/vnode.9 index 3d34b48c2ee0..d17492668298 100644 --- a/share/man/man9/vnode.9 +++ b/share/man/man9/vnode.9 @@ -24,7 +24,7 @@ .\" (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 February 12, 2014 +.Dd July 15, 2025 .Dt VNODE 9 .Os .Sh NAME @@ -104,9 +104,21 @@ the vnode. The .Va v_op field is used by the -.Dv VOP_* -macros to call functions in the file system which implement the vnode's +.Fn VOP_* +functions to call functions in the file system which implement the vnode's functionality. +.Pp +The +.Fn VOP_* +function declarations and definitions are generated from +.Pa sys/kern/vnode_if.src +by the +.Pa sys/tools/vnode_if.awk +script. +The interfaces are documented in their respective manual pages like +.Xr VOP_READ 9 +and +.Xr VOP_WRITE 9 . .Sh VNODE TYPES .Bl -tag -width VSOCK .It Dv VNON @@ -154,6 +166,16 @@ when holding a .Nm interlock, will cause a LOR (Lock Order Reversal) due to the intertwining of VM Objects and Vnodes. +.Sh FILES +.Bl -tag -width "sys/tools/vnode_if.awk" -compact +.It Pa sys/kern/vnode_if.src +The input file for +.Pa sys/tools/vnode_if.awk . +.It Pa sys/tools/vnode_if.awk +The script generating the source code of the +.Fn VOP_* +functions. +.El .Sh SEE ALSO .Xr malloc 9 , .Xr VFS 9 , diff --git a/share/man/man9/zone.9 b/share/man/man9/zone.9 index a6b8d2dfedbe..9f13cf0e504a 100644 --- a/share/man/man9/zone.9 +++ b/share/man/man9/zone.9 @@ -341,7 +341,7 @@ Create a zone whose items will be synchronized using the .Xr smr 9 mechanism. Upon creation the zone will have an associated -.Dt smr_t +.Ft smr_t structure which can be fetched using .Fn uma_zone_get_smr . .El |